langsmith-sdk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd9018b27dbb87f1518a96570bedf1bf7b09702b18816f072f9764075cb6adf8
+  data.tar.gz: d69c6d0194c193fbb8567beb42d98042fa2e36fe24e855a0429753d7440efc63
+SHA512:
+  metadata.gz: 156b32b2b1c09ef127183b8899dda9ba58bd837895b0baeb36074bc507b1ebed4a959847a9ca71b7dfaac93bcd8d0f35afe7a5aa9677ff8e9959c0a1132d4e56
+  data.tar.gz: '08a7208efb8a94a5d8a798fa4a3d490575342ca807629a0ba43e577ad7fb9c0f15c0c0476cc65067c1540f127332f9a79ebe07b2047a3c922f721f6bb56f1f17'

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+

data/.rubocop.yml

@@ -0,0 +1,120 @@
+# RuboCop configuration for langsmith-sdk-ruby
+# Run: bundle exec rubocop
+
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'examples/**/*'
+    - '*.gemspec'
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns:
+    - '^\s*#'  # Allow long comments
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+# Metrics
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/AbcSize:
+  Max: 32
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+# Data classes and API methods often need many parameters
+# Run.new needs all trace attributes, trace() accepts many options
+Metrics/ParameterLists:
+  Max: 8
+  CountKeywordArgs: false  # Keyword args are self-documenting, less problematic
+
+# Style
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+
+# Naming
+Naming/MethodParameterName:
+  AllowedNames:
+    - id
+    - e
+
+# Renamed from PredicateName in newer rubocop
+Naming/PredicatePrefix:
+  Enabled: false
+
+# Allow set_ prefix for explicit setter methods (set_inputs, set_outputs, set_token_usage)
+# These are intentionally named to be explicit about mutation vs simple assignment
+Naming/AccessorMethodName:
+  Enabled: false
+
+# RSpec
+RSpec/MultipleExpectations:
+  Max: 6
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/langsmith_spec.rb'
+
+RSpec/MessageSpies:
+  EnforcedStyle: have_received
+
+RSpec/VerifiedDoubles:
+  Enabled: true
+
+# Numbered let names like run1, run2 are clear in batch processing tests
+RSpec/IndexedLet:
+  Enabled: false
+
+# receive_messages is often less readable than separate stubs
+RSpec/ReceiveMessages:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.1

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2025-12-21
+
+### Added
+
+- Per-trace `project` parameter to override the default project at runtime
+- Child traces automatically inherit project from parent (enforced)
+
+## [0.1.0] - 2025-12-21
+
+### Added
+
+- Initial release of the LangSmith Ruby SDK
+- Block-based tracing with `Langsmith.trace`
+- Method decoration with `Langsmith::Traceable` module
+- Automatic parent-child trace linking for nested traces
+- Thread-safe batch processing with background worker
+- Thread-local context for proper isolation in concurrent environments
+- Multi-tenant support with per-trace `tenant_id` override
+- Token usage tracking with `set_token_usage`
+- Model metadata with `set_model`
+- Streaming metrics with `set_streaming_metrics`
+- Event tracking with `add_event`
+- Configurable via environment variables or programmatic configuration
+- Automatic retry with exponential backoff for failed API requests
+- Graceful shutdown with `at_exit` hook
+
+### Run Types
+
+- `chain` - A sequence of operations
+- `llm` - LLM API calls
+- `tool` - Tool/function executions
+- `retriever` - Document retrieval operations
+- `prompt` - Prompt template rendering
+- `parser` - Output parsing operations
+
+[Unreleased]: https://github.com/felipekb/langsmith-ruby-sdk/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/felipekb/langsmith-ruby-sdk/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/felipekb/langsmith-ruby-sdk/releases/tag/v0.1.0
+

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Felipe Cabezudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,224 @@
+# LangSmith Ruby SDK
+
+A Ruby SDK for [LangSmith](https://smith.langchain.com/) tracing and observability.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'langsmith-sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install langsmith-sdk
+```
+
+## Configuration
+
+Set up your LangSmith credentials via environment variables:
+
+```bash
+export LANGSMITH_API_KEY=ls_...
+export LANGSMITH_TRACING=true
+export LANGSMITH_PROJECT=my-project   # optional, defaults to "default"
+export LANGSMITH_TENANT_ID=tenant-123 # optional, for multi-tenant scenarios
+```
+
+Or configure programmatically:
+
+```ruby
+Langsmith.configure do |config|
+  config.api_key = "ls_..."
+  config.tracing_enabled = true
+  config.project = "my-project"
+  config.tenant_id = "tenant-123" # optional, for multi-tenant scenarios
+end
+```
+
+## Usage
+
+### Block-based Tracing
+
+```ruby
+require "langsmith"
+
+result = Langsmith.trace("my_operation", run_type: "chain") do |run|
+  run.add_metadata(user_id: "123")
+
+  # Your code here
+  response = call_llm(prompt)
+
+  response
+end
+```
+
+### Nested Traces
+
+Traces automatically nest when called within other traces:
+
+```ruby
+Langsmith.trace("parent_chain", run_type: "chain") do
+  # This will be a child of parent_chain
+  Langsmith.trace("child_llm_call", run_type: "llm") do
+    call_openai(prompt)
+  end
+
+  # Another child
+  Langsmith.trace("child_tool", run_type: "tool") do
+    search_database(query)
+  end
+end
+```
+
+### Method Decoration with Traceable
+
+```ruby
+class MyService
+  include Langsmith::Traceable
+
+  traceable run_type: "chain"
+  def process(input)
+    # This method is automatically traced
+    transform(input)
+  end
+
+  traceable run_type: "llm", name: "openai_call"
+  def call_llm(prompt)
+    # Traced with custom name
+    client.chat(prompt)
+  end
+end
+```
+
+## Run Types
+
+Supported run types:
+- `"chain"` - A sequence of operations
+- `"llm"` - LLM API calls
+- `"tool"` - Tool/function executions
+- `"retriever"` - Document retrieval operations
+- `"prompt"` - Prompt template rendering
+- `"parser"` - Output parsing operations
+
+## Per-Trace Project Override
+
+You can override the project for specific traces at runtime:
+
+```ruby
+# Override project for a specific trace (and its children)
+Langsmith.trace("operation", project: "my-special-project") do
+  # This trace goes to "my-special-project"
+
+  # Nested traces inherit project from parent automatically
+  Langsmith.trace("child") do
+    # Also goes to "my-special-project"
+  end
+end
+```
+
+
+## Multi-Tenant Support
+
+For multi-tenant scenarios, you can set a global tenant ID or override it per-trace:
+
+### Global Configuration
+
+```ruby
+Langsmith.configure do |config|
+  config.tenant_id = "tenant-123"
+end
+
+# All traces will use tenant-123
+Langsmith.trace("operation") do
+  # ...
+end
+```
+
+### Per-Trace Override
+
+```ruby
+# Override tenant for a specific trace (and its children)
+Langsmith.trace("operation", tenant_id: "tenant-456") do
+  # This trace goes to tenant-456
+
+  # Nested traces inherit tenant_id from parent
+  Langsmith.trace("child") do
+    # Also goes to tenant-456
+  end
+end
+```
+
+### With Traceable Module
+
+```ruby
+class MultiTenantService
+  include Langsmith::Traceable
+
+  traceable run_type: "chain", tenant_id: "tenant-123"
+  def process_for_tenant_123(data)
+    # Always traced to tenant-123
+  end
+
+  traceable run_type: "chain", tenant_id: "tenant-456"
+  def process_for_tenant_456(data)
+    # Always traced to tenant-456
+  end
+end
+```
+
+The SDK automatically batches traces by tenant ID, so traces for different tenants are sent in separate API requests with the appropriate `X-Tenant-Id` header.
+
+## Token Usage Tracking
+
+Track token usage for LLM calls:
+
+```ruby
+Langsmith.trace("openai_call", run_type: "llm") do |run|
+  response = openai_client.chat(parameters: { model: "gpt-4", messages: messages })
+
+  # Set model info (displayed in LangSmith UI)
+  run.set_model(model: "gpt-4", provider: "openai")
+
+  # Set token usage from API response
+  run.set_token_usage(
+    input_tokens: response["usage"]["prompt_tokens"],
+    output_tokens: response["usage"]["completion_tokens"],
+    total_tokens: response["usage"]["total_tokens"]
+  )
+
+  # Add additional metadata
+  run.add_metadata(finish_reason: response.dig("choices", 0, "finish_reason"))
+
+  response.dig("choices", 0, "message", "content")
+end
+```
+
+## Examples
+
+See [`examples/LLM_TRACING.md`](examples/LLM_TRACING.md) for comprehensive examples including:
+
+- Basic LLM calls with token usage
+- Streaming responses
+- Multi-step chains (RAG)
+- OpenAI and Anthropic integrations
+- Error handling and retries
+- Multi-tenant tracing
+- Per-trace project overrides
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec