v0.5.0 separate http(x) clients (#99)

* wip: httpx client objects

* add agent run

* fix: playwright, TODO: cleanup

* slight refactor

* bump version, unify initialization, minor updates

* fix action

* minor fixes, doc comments, renames

* span_context 2 parent_span_context, remove cdp_url

* fix doc comments

* fix in doc comment

* update spanContext serde

* fix tests

* set current context as parent

* fix parent span context

* remove redundant method

* allow shutdown without init

* some renames, close browser span immediately

* raise the error if the eval is broken

* add base url to evals

* don't add browsertype.connect if there is an active span

* minor fixes

* add shutdown in evals, increase httpx timeout to 1h

* Update README.md

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

* Update README.md

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

* small fixes in README

* Update README.md

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

* allow deserializing camelCase as well

* remove agent state str

---------

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

Author: dinmukhamedm

.github/workflows/ensure-version-match.yml

@@ -18,7 +18,7 @@ jobs:
       run: uv add toml-cli
     - name: Ensure version match
       run: |
-        SDK_VERSION=$(cat src/lmnr/version.py | grep SDK_VERSION | head -n1 | cut -d'=' -f2 | sed 's/[" '"'"']//g')
+        SDK_VERSION=$(cat src/lmnr/version.py | grep __version__ | head -n1 | cut -d'=' -f2 | sed 's/[" '"'"']//g')
         PYPROJECT_VERSION=$(uv run toml get --toml-path=pyproject.toml project.version)
         if [ "$SDK_VERSION" != "$PYPROJECT_VERSION" ]; then
           echo "Version mismatch between src/lmnr/version.py and pyproject.toml"

README.md

@@ -35,7 +35,28 @@ from lmnr import Laminar
 Laminar.initialize(project_api_key="<PROJECT_API_KEY>")
 ```
 
-Note that you need to only initialize Laminar once in your application.
+You can also skip passing the `project_api_key`, in which case it will be looked
+in the environment (or local .env file) by the key `LMNR_PROJECT_API_KEY`.
+
+Note that you need to only initialize Laminar once in your application. You should
+try to do that as early as possible in your application, e.g. at server startup.
+
+## Set-up for self-hosting
+
+If you self-host a Laminar instance, the default connection settings to it are
+`http://localhost:8000` for HTTP and `http://localhost:8001` for gRPC. Initialize
+the SDK accordingly:
+
+```python
+from lmnr import Laminar
+
+Laminar.initialize(
+    project_api_key="<PROJECT_API_KEY>",
+    base_url="http://localhost",
+    http_port=8000,
+    grpc_port=8001,
+)
+```
 
 ## Instrumentation
 
@@ -171,49 +192,78 @@ You can run evaluations locally by providing executor (part of the logic used in
 
 Read the [docs](https://docs.lmnr.ai/evaluations/introduction) to learn more about evaluations.
 
-## Laminar pipelines as prompt chain managers
+## Client for HTTP operations
 
-You can create Laminar pipelines in the UI and manage chains of LLM calls there.
+Various interactions with Laminar [API](https://docs.lmnr.ai/api-reference/) are available in `LaminarClient`
+and its asynchronous version `AsyncLaminarClient`.
 
-After you are ready to use your pipeline in your code, deploy it in Laminar by selecting the target version for the pipeline.
+### Agent
 
-Once your pipeline target is set, you can call it from Python in just a few lines.
-
-Example use:
+To run Laminar agent, you can invoke `client.agent.run`
 
 ```python
-from lmnr import Laminar
+from lmnr import LaminarClient
 
-Laminar.initialize('<YOUR_PROJECT_API_KEY>', instruments=set())
+client = LaminarClient(project_api_key="<YOUR_PROJECT_API_KEY>")
 
-result = Laminar.run(
-    pipeline = 'my_pipeline_name',
-    inputs = {'input_node_name': 'some_value'},
-    # all environment variables
-    env = {'OPENAI_API_KEY': 'sk-some-key'},
+response = client.agent.run(
+    prompt="What is the weather in London today?"
 )
+
+print(response.result.content)
 ```
 
-Resulting in:
+#### Streaming
+
+Agent run supports streaming as well.
 
 ```python
->>> result
-PipelineRunResponse(
-    outputs={'output': {'value': [ChatMessage(role='user', content='hello')]}},
-    # useful to locate your trace
-    run_id='53b012d5-5759-48a6-a9c5-0011610e3669'
-)
+from lmnr import LaminarClient
+
+client = LaminarClient(project_api_key="<YOUR_PROJECT_API_KEY>")
+
+for chunk in client.agent.run(
+    prompt="What is the weather in London today?",
+    stream=True
+):
+    if chunk.chunkType == 'step':
+        print(chunk.summary)
+    elif chunk.chunkType == 'finalOutput':
+        print(chunk.content.result.content)
 ```
 
-## Semantic search
-
-You can perform a semantic search on a dataset in Laminar by calling `Laminar.semantic_search`.
+#### Async mode
 
 ```python
-response = Laminar.semantic_search(
-    query="Greatest Chinese architectural wonders",
-    dataset_id=uuid.UUID("413f8404-724c-4aa4-af16-714d84fd7958"),
+from lmnr import AsyncLaminarClient
+
+client = AsyncLaminarClient(project_api_key="<YOUR_PROJECT_API_KEY>")
+
+response = await client.agent.run(
+    prompt="What is the weather in London today?"
 )
+
+print(response.result.content)
 ```
 
-[Read more](https://docs.lmnr.ai/datasets/indexing) about indexing and semantic search.
+#### Async mode with streaming
+
+```python
+from lmnr import AsyncLaminarClient
+
+client = AsyncLaminarClient(project_api_key="<YOUR_PROJECT_API_KEY>")
+
+# Note that you need to await the operation even though we use `async for` below
+response = await client.agent.run(
+    prompt="What is the weather in London today?",
+    stream=True
+)
+async for chunk in client.agent.run(
+    prompt="What is the weather in London today?",
+    stream=True
+):
+    if chunk.chunkType == 'step':
+        print(chunk.summary)
+    else if chunk.chunkType == 'finalOutput':
+        print(chunk.content.result.content)
+```

pyproject.toml

@@ -6,7 +6,7 @@
 
 [project]
 name = "lmnr"
-version = "0.4.66"
+version = "0.5.0"
 description = "Python SDK for Laminar"
 authors = [
   { name = "lmnr.ai", email = "[email protected]" }
@@ -16,20 +16,18 @@ requires-python = ">=3.9,<4"
 license = "Apache-2.0"
 dependencies = [
   "pydantic (>=2.0.3)",
-  "requests (>=2.0)",
   "python-dotenv (>=1.0)",
-  "opentelemetry-api (>=1.28.0)",
-  "opentelemetry-sdk (>=1.28.0)",
-  "opentelemetry-exporter-otlp-proto-http (>=1.28.0)",
-  "opentelemetry-exporter-otlp-proto-grpc (>=1.28.0)",
-  "opentelemetry-instrumentation-requests (>=0.50b0)",
-  "opentelemetry-instrumentation-sqlalchemy (>=0.50b0)",
-  "opentelemetry-instrumentation-urllib3 (>=0.50b0)",
-  "opentelemetry-instrumentation-threading (>=0.50b0)",
+  "opentelemetry-api (>=1.31.1)",
+  "opentelemetry-sdk (>=1.31.1)",
+  "opentelemetry-exporter-otlp-proto-http (>=1.31.1)",
+  "opentelemetry-exporter-otlp-proto-grpc (>=1.31.1)",
+  "opentelemetry-instrumentation-requests (>=0.52b0)",
+  "opentelemetry-instrumentation-sqlalchemy (>=0.52b0)",
+  "opentelemetry-instrumentation-urllib3 (>=0.52b0)",
+  "opentelemetry-instrumentation-threading (>=0.52b0)",
   "opentelemetry-semantic-conventions-ai (>=0.4.2)",
   "tqdm (>=4.0)",
   "argparse (>=1.0)",
-  "aiohttp (>=3.0)",
   "tenacity (>=8.0)",
   # explicitly freeze grpcio. Since 1.68.0, grpcio writes a warning message
   # that looks scary, but is harmless.
@@ -40,6 +38,7 @@ dependencies = [
   # https://discuss.ai.google.dev/t/warning-all-log-messages-before-absl-initializelog-is-called-are-written-to-stderr-e0000-001731955515-629532-17124-init-cc-229-grpc-wait-for-shutdown-with-timeout-timed-out/50020
   # https://github.com/grpc/grpc/issues/38490
   "grpcio<1.68.0",
+  "httpx>=0.28.1",
 ]
 
 [project.scripts]
@@ -114,7 +113,8 @@ dev = [
   "flake8",
   "pytest>=8.3.4",
   "pytest-sugar",
-  "pytest-asyncio>=0.25.2"
+  "pytest-asyncio>=0.25.2",
+  "playwright>=1.51.0"
 ]
 
 [build-system]

src/lmnr/__init__.py

@@ -1,16 +1,46 @@
+from .sdk.client.synchronous.sync_client import LaminarClient
+from .sdk.client.asynchronous.async_client import AsyncLaminarClient
 from .sdk.datasets import EvaluationDataset, LaminarDataset
 from .sdk.evaluations import evaluate
 from .sdk.laminar import Laminar
 from .sdk.types import (
+    AgentOutput,
+    FinalOutputChunkContent,
     ChatMessage,
     HumanEvaluator,
     NodeInput,
     PipelineRunError,
     PipelineRunResponse,
+    RunAgentResponseChunk,
+    StepChunkContent,
     TracingLevel,
 )
 from .sdk.decorators import observe
 from .sdk.types import LaminarSpanContext
 from .openllmetry_sdk import Instruments
 from .openllmetry_sdk.tracing.attributes import Attributes
 from opentelemetry.trace import use_span
+
+__all__ = [
+    "AgentOutput",
+    "AsyncLaminarClient",
+    "Attributes",
+    "ChatMessage",
+    "EvaluationDataset",
+    "FinalOutputChunkContent",
+    "HumanEvaluator",
+    "Instruments",
+    "Laminar",
+    "LaminarClient",
+    "LaminarDataset",
+    "LaminarSpanContext",
+    "NodeInput",
+    "PipelineRunError",
+    "PipelineRunResponse",
+    "RunAgentResponseChunk",
+    "StepChunkContent",
+    "TracingLevel",
+    "evaluate",
+    "observe",
+    "use_span",
+]

src/lmnr/openllmetry_sdk/__init__.py

@@ -16,7 +16,7 @@
 from typing import Dict
 
 
-class Traceloop:
+class TracerManager:
     __tracer_wrapper: TracerWrapper
 
     @staticmethod
@@ -44,17 +44,6 @@ def init(
         if isinstance(headers, str):
             headers = parse_env_headers(headers)
 
-        if (
-            not exporter
-            and not processor
-            and api_endpoint == "https://api.lmnr.ai"
-            and not api_key
-        ):
-            print(
-                "Set the LMNR_PROJECT_API_KEY environment variable to your project API key"
-            )
-            return
-
         if api_key and not exporter and not processor and not headers:
             headers = {
                 "Authorization": f"Bearer {api_key}",
@@ -65,7 +54,7 @@ def init(
         TracerWrapper.set_static_params(
             resource_attributes, enable_content_tracing, api_endpoint, headers
         )
-        Traceloop.__tracer_wrapper = TracerWrapper(
+        TracerManager.__tracer_wrapper = TracerWrapper(
             disable_batch=disable_batch,
             processor=processor,
             propagator=propagator,
@@ -79,5 +68,5 @@ def init(
 
     @staticmethod
     def flush():
-        if Traceloop.__tracer_wrapper:
-            Traceloop.__tracer_wrapper.flush()
+        if getattr(TracerManager, "__tracer_wrapper", None):
+            TracerManager.__tracer_wrapper.flush()

src/lmnr/openllmetry_sdk/tracing/attributes.py

@@ -9,7 +9,6 @@
 SPAN_INSTRUMENTATION_SOURCE = "lmnr.span.instrumentation_source"
 SPAN_SDK_VERSION = "lmnr.span.sdk_version"
 SPAN_LANGUAGE_VERSION = "lmnr.span.language_version"
-OVERRIDE_PARENT_SPAN = "lmnr.internal.override_parent_span"
 
 ASSOCIATION_PROPERTIES = "lmnr.association.properties"
 SESSION_ID = "session_id"