Set global configuration (#2002)

It's nice if you can configure stuff (like metadata, etc.) at the module
level, especially for scnearios like LGP.

```
import langsmith as ls

ls.configure(metadata={"revision": "foo", "bar": "baz})
```

RIght now if you do .configure() and then do asyncio.run() etc., the
contextvar can be lost (need to copycontext())

he expectation for .configure() is that it works like logging
configuration and is global. if you want to set something in context you
use `tracing_context`. That's the point of that function.

This pr also does some cleanup of contextvars definitions and also sets
a globally scoped default for metadata, etc. so that metadata doesn't
get lost in async tasks.

Author: hinthornw

python/langsmith/__init__.py

@@ -21,7 +21,7 @@
 
 # Avoid calling into importlib on every call to __version__
 
-__version__ = "0.4.26"
+__version__ = "0.4.27"
 version = __version__  # for backwards compatibility
 
 

python/langsmith/_internal/_context.py

@@ -0,0 +1,29 @@
+"""Shared context (ContextVars and global defaults) that configure tracing."""
+
+import contextvars
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union
+
+if TYPE_CHECKING:
+    from langsmith.client import Client
+    from langsmith.run_trees import RunTree
+else:
+    Client = Any  # type: ignore[assignment]
+    RunTree = Any  # type: ignore[assignment]
+
+_PROJECT_NAME = contextvars.ContextVar[Optional[str]]("_PROJECT_NAME", default=None)
+_TAGS = contextvars.ContextVar[Optional[list[str]]]("_TAGS", default=None)
+_METADATA = contextvars.ContextVar[Optional[dict[str, Any]]]("_METADATA", default=None)
+
+_TRACING_ENABLED = contextvars.ContextVar[Optional[Union[bool, Literal["local"]]]](
+    "_TRACING_ENABLED", default=None
+)
+_CLIENT = contextvars.ContextVar[Optional["Client"]]("_CLIENT", default=None)
+_PARENT_RUN_TREE = contextvars.ContextVar[Optional["RunTree"]](
+    "_PARENT_RUN_TREE", default=None
+)
+# Not thread-local, so you can set this process-wide (before asyncio.run, etc.)
+_GLOBAL_PROJECT_NAME: Optional[str] = None
+_GLOBAL_TAGS: Optional[list[str]] = None
+_GLOBAL_METADATA: Optional[dict[str, Any]] = None
+_GLOBAL_TRACING_ENABLED: Optional[Union[bool, Literal["local"]]] = None
+_GLOBAL_CLIENT: Optional["Client"] = None

python/langsmith/run_helpers.py

@@ -41,6 +41,7 @@
 
 from typing_extensions import ParamSpec, TypeGuard, get_args, get_origin
 
+import langsmith._internal._context as _context
 from langsmith import client as ls_client
 from langsmith import run_trees, schemas, utils
 from langsmith._internal import _aiter as aitertools
@@ -53,25 +54,13 @@
     from langchain_core.runnables import Runnable
 
 LOGGER = logging.getLogger(__name__)
-_PARENT_RUN_TREE = contextvars.ContextVar[Optional[run_trees.RunTree]](
-    "_PARENT_RUN_TREE", default=None
-)
-_PROJECT_NAME = contextvars.ContextVar[Optional[str]]("_PROJECT_NAME", default=None)
-_TAGS = contextvars.ContextVar[Optional[list[str]]]("_TAGS", default=None)
-_METADATA = contextvars.ContextVar[Optional[dict[str, Any]]]("_METADATA", default=None)
-
-
-_TRACING_ENABLED = contextvars.ContextVar[Optional[Union[bool, Literal["local"]]]](
-    "_TRACING_ENABLED", default=None
-)
-_CLIENT = contextvars.ContextVar[Optional[ls_client.Client]]("_CLIENT", default=None)
 _CONTEXT_KEYS: dict[str, contextvars.ContextVar] = {
-    "parent": _PARENT_RUN_TREE,
-    "project_name": _PROJECT_NAME,
-    "tags": _TAGS,
-    "metadata": _METADATA,
-    "enabled": _TRACING_ENABLED,
-    "client": _CLIENT,
+    "parent": _context._PARENT_RUN_TREE,
+    "project_name": _context._PROJECT_NAME,
+    "tags": _context._TAGS,
+    "metadata": _context._METADATA,
+    "enabled": _context._TRACING_ENABLED,
+    "client": _context._CLIENT,
     "replicas": run_trees._REPLICAS,
     "distributed_parent_id": run_trees._DISTRIBUTED_PARENT_ID,
 }
@@ -83,7 +72,7 @@
 
 def get_current_run_tree() -> Optional[run_trees.RunTree]:
     """Get the current run tree."""
-    return _PARENT_RUN_TREE.get()
+    return _context._PARENT_RUN_TREE.get()
 
 
 def get_tracing_context(
@@ -92,12 +81,12 @@ def get_tracing_context(
     """Get the current tracing context."""
     if context is None:
         return {
-            "parent": _PARENT_RUN_TREE.get(),
-            "project_name": _PROJECT_NAME.get(),
-            "tags": _TAGS.get(),
-            "metadata": _METADATA.get(),
-            "enabled": _TRACING_ENABLED.get(),
-            "client": _CLIENT.get(),
+            "parent": _context._PARENT_RUN_TREE.get(),
+            "project_name": _context._PROJECT_NAME.get(),
+            "tags": _context._TAGS.get(),
+            "metadata": _context._METADATA.get(),
+            "enabled": _context._TRACING_ENABLED.get(),
+            "client": _context._CLIENT.get(),
             "replicas": run_trees._REPLICAS.get(),
             "distributed_parent_id": run_trees._DISTRIBUTED_PARENT_ID.get(),
         }
@@ -995,8 +984,8 @@ def _setup(self) -> run_trees.RunTree:
         self.old_ctx = get_tracing_context()
         enabled = utils.tracing_is_enabled(self.old_ctx)
 
-        outer_tags = _TAGS.get()
-        outer_metadata = _METADATA.get()
+        outer_tags = _context._TAGS.get() or _context._GLOBAL_TAGS
+        outer_metadata = _context._METADATA.get() or _context._GLOBAL_METADATA
         client_ = self.client or self.old_ctx.get("client")
         parent_run_ = _get_parent_run(
             {
@@ -1049,11 +1038,11 @@ def _setup(self) -> run_trees.RunTree:
         if enabled is True:
             self.new_run.post()
         if enabled:
-            _TAGS.set(tags_)
-            _METADATA.set(metadata)
-            _PARENT_RUN_TREE.set(self.new_run)
-            _PROJECT_NAME.set(project_name_)
-            _CLIENT.set(client_)
+            _context._TAGS.set(tags_)
+            _context._METADATA.set(metadata)
+            _context._PARENT_RUN_TREE.set(self.new_run)
+            _context._PROJECT_NAME.set(project_name_)
+            _context._CLIENT.set(client_)
 
         return self.new_run
 
@@ -1161,8 +1150,10 @@ def _get_project_name(project_name: Optional[str]) -> Optional[str]:
     prt = _PARENT_RUN_TREE.get()
     return (
         # Maintain tree consistency first
-        _PROJECT_NAME.get()
+        _context._PROJECT_NAME.get()
         or (prt.session_name if prt else None)
+        # Global fallback configured via ls.configure(...)
+        or _context._GLOBAL_PROJECT_NAME
         # fallback to the default for the environment
         or utils.get_tracer_project()
     )
@@ -1453,21 +1444,22 @@ def _setup_run(
     dangerously_allow_filesystem = container_input.get(
         "dangerously_allow_filesystem", False
     )
-    outer_project = _PROJECT_NAME.get()
+    outer_project = _context._PROJECT_NAME.get()
     langsmith_extra = langsmith_extra or LangSmithExtra()
     name = langsmith_extra.get("name") or container_input.get("name")
-    client_ = langsmith_extra.get("client", client) or _CLIENT.get()
+    client_ = langsmith_extra.get("client", client) or _context._CLIENT.get()
     parent_run_ = _get_parent_run(
         {**langsmith_extra, "client": client_}, kwargs.get("config")
     )
-    project_cv = _PROJECT_NAME.get()
+    project_cv = _context._PROJECT_NAME.get()
     selected_project = (
         project_cv  # From parent trace
         or (
             parent_run_.session_name if parent_run_ else None
         )  # from parent run attempt 2 (not managed by traceable)
         or langsmith_extra.get("project_name")  # at invocation time
         or container_input["project_name"]  # at decorator time
+        or _context._GLOBAL_PROJECT_NAME  # global fallback from ls.configure
         or utils.get_tracer_project()  # default
     )
     reference_example_id = langsmith_extra.get("reference_example_id")
@@ -1492,14 +1484,14 @@ def _setup_run(
     signature = inspect.signature(func)
     name_ = name or utils._get_function_name(func)
     extra_inner = _collect_extra(extra_outer, langsmith_extra)
-    outer_metadata = _METADATA.get()
-    outer_tags = _TAGS.get()
+    outer_metadata = _context._METADATA.get() or _context._GLOBAL_METADATA
+    outer_tags = _context._TAGS.get() or _context._GLOBAL_TAGS
     context = copy_context()
     metadata_ = {
         **(langsmith_extra.get("metadata") or {}),
         **(outer_metadata or {}),
     }
-    context.run(_METADATA.set, metadata_)
+    context.run(_context._METADATA.set, metadata_)
     metadata_.update(metadata or {})
     metadata_["ls_method"] = "traceable"
     extra_inner["metadata"] = metadata_
@@ -1523,7 +1515,7 @@ def _setup_run(
         except BaseException as e:
             LOGGER.error(f"Failed to filter inputs for {name_}: {e}")
     tags_ = (langsmith_extra.get("tags") or []) + (outer_tags or [])
-    context.run(_TAGS.set, tags_)
+    context.run(_context._TAGS.set, tags_)
     tags_ += tags or []
     if parent_run_ is not None:
         new_run = parent_run_.create_child(
@@ -1568,7 +1560,7 @@ def _setup_run(
         context=context,
         _token_event_logged=False,
     )
-    context.run(_PROJECT_NAME.set, response_container["project_name"])
+    context.run(_context._PROJECT_NAME.set, response_container["project_name"])
     context.run(_PARENT_RUN_TREE.set, response_container["new_run"])
     return response_container
 
@@ -2081,3 +2073,12 @@ def _maybe_create_otel_context(run_tree: Optional[run_trees.RunTree]):
 
     non_recording_span = NonRecordingSpan(span_context)
     return use_span(non_recording_span)
+
+
+# For backwards compatibility
+_PROJECT_NAME = _context._PROJECT_NAME
+_TAGS = _context._TAGS
+_METADATA = _context._METADATA
+_TRACING_ENABLED = _context._TRACING_ENABLED
+_CLIENT = _context._CLIENT
+_PARENT_RUN_TREE = _context._PARENT_RUN_TREE

python/langsmith/run_trees.py

@@ -25,6 +25,7 @@
 import threading
 import urllib.parse
 
+import langsmith._internal._context as _context
 from langsmith import schemas as ls_schemas
 from langsmith import utils
 from langsmith.client import ID_TYPE, RUN_TYPE_T, Client, _dumps_json, _ensure_uuid
@@ -48,7 +49,6 @@ class WriteReplica(TypedDict, total=False):
 LANGSMITH_REPLICAS = sys.intern(f"{LANGSMITH_PREFIX}replicas")
 OVERRIDE_OUTPUTS = sys.intern("__omit_auto_outputs")
 NOT_PROVIDED = cast(None, object())
-_CLIENT: Optional[Client] = None
 _LOCK = threading.Lock()
 
 # Context variables
@@ -147,21 +147,17 @@ def configure(
         if client is not _SENTINEL:
             _CLIENT = client
         if enabled is not _SENTINEL:
-            from langsmith.run_helpers import _TRACING_ENABLED
-
-            _TRACING_ENABLED.set(enabled)
+            _context._TRACING_ENABLED.set(enabled)
+            _context._GLOBAL_TRACING_ENABLED = enabled
         if project_name is not _SENTINEL:
-            from langsmith.run_helpers import _PROJECT_NAME
-
-            _PROJECT_NAME.set(project_name)
+            _context._PROJECT_NAME.set(project_name)
+            _context._GLOBAL_PROJECT_NAME = project_name
         if tags is not _SENTINEL:
-            from langsmith.run_helpers import _TAGS
-
-            _TAGS.set(tags)
+            _context._TAGS.set(tags)
+            _context._GLOBAL_TAGS = tags
         if metadata is not _SENTINEL:
-            from langsmith.run_helpers import _METADATA
-
-            _METADATA.set(metadata)
+            _context._METADATA.set(metadata)
+            _context._GLOBAL_METADATA = metadata
 
 
 def validate_extracted_usage_metadata(
@@ -1129,4 +1125,5 @@ def _create_current_dotted_order(
     return st.strftime("%Y%m%dT%H%M%S%fZ") + str(id_)
 
 
+_CLIENT: Optional[Client] = _context._GLOBAL_CLIENT
 __all__ = ["RunTree", "RunTree"]

python/langsmith/utils.py

@@ -98,6 +98,8 @@ class LangSmithMissingAPIKeyWarning(LangSmithWarning):
 
 def tracing_is_enabled(ctx: Optional[dict] = None) -> Union[bool, Literal["local"]]:
     """Return True if tracing is enabled."""
+    # Access global fallbacks via context module to avoid stale references.
+    import langsmith._internal._context as _context
     from langsmith.run_helpers import get_current_run_tree, get_tracing_context
 
     tc = ctx or get_tracing_context()
@@ -110,6 +112,9 @@ def tracing_is_enabled(ctx: Optional[dict] = None) -> Union[bool, Literal["local
     # Next check if we're mid-trace
     if get_current_run_tree():
         return True
+    # If a global fallback was configured, use it next.
+    if _context._GLOBAL_TRACING_ENABLED is not None:
+        return _context._GLOBAL_TRACING_ENABLED
     # Finally, check the global environment
     var_result = get_env_var("TRACING_V2", default=get_env_var("TRACING", default=""))
     return var_result == "true"

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langsmith"
-version = "0.4.26"
+version = "0.4.27"
 description = "Client library to connect to the LangSmith LLM Tracing and Evaluation Platform."
 authors = [
     {name = "LangChain", email = "[email protected]"},