lightrace 0.1.1__tar.gz

lightrace-0.1.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2

lightrace-0.1.1/.env.example

@@ -0,0 +1,3 @@
+LIGHTRACE_HOST=http://localhost:3002
+LIGHTRACE_PUBLIC_KEY=pk-lt-demo
+LIGHTRACE_SECRET_KEY=sk-lt-demo

lightrace-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Feature Request
+    url: https://github.com/SKE-Labs/lightrace-python/discussions/categories/ideas
+    about: Suggest a feature or improvement
+  - name: Get Help
+    url: https://github.com/SKE-Labs/lightrace-python/discussions/categories/q-a
+    about: Ask questions and get help from the community

lightrace-0.1.1/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore"
+      include: scope

lightrace-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- Brief description of the changes -->
+
+## Changes
+
+-
+
+## Testing
+
+- [ ] Tests pass (`pytest -s -v tests/`)
+- [ ] Lint passes (`ruff check .`)
+- [ ] Types check (`mypy src/lightrace`)

lightrace-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run mypy src/lightrace --no-error-summary
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run pytest -s -v tests/
+
+  all-checks-passed:
+    name: All Checks Passed
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    if: always()
+    steps:
+      - run: |
+          if [ "${{ needs.lint.result }}" != "success" ] || \
+             [ "${{ needs.typecheck.result }}" != "success" ] || \
+             [ "${{ needs.test.result }}" != "success" ]; then
+            exit 1
+          fi

lightrace-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      dry-run:
+        description: "Dry run (no publish)"
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -s -v tests/
+
+      - name: Bump version
+        run: |
+          CURRENT=$(uv run python -c "from lightrace.version import __version__; print(__version__)")
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          case "${{ inputs.version }}" in
+            major) NEW="$((MAJOR+1)).0.0" ;;
+            minor) NEW="${MAJOR}.$((MINOR+1)).0" ;;
+            patch) NEW="${MAJOR}.${MINOR}.$((PATCH+1))" ;;
+          esac
+          echo "NEW_VERSION=$NEW" >> $GITHUB_ENV
+          sed -i "s/version = \"$CURRENT\"/version = \"$NEW\"/" pyproject.toml
+          sed -i "s/__version__ = \"$CURRENT\"/__version__ = \"$NEW\"/" src/lightrace/version.py
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        if: ${{ !inputs.dry-run }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Commit & tag
+        if: ${{ !inputs.dry-run }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml src/lightrace/version.py
+          git commit -m "chore: release v${{ env.NEW_VERSION }}"
+          git tag "v${{ env.NEW_VERSION }}"
+          git push && git push --tags
+
+      - name: Create GitHub Release
+        if: ${{ !inputs.dry-run }}
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ env.NEW_VERSION }}
+          generate_release_notes: true

lightrace-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.python-version
+.env
+.venv/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+coverage.xml
+.coverage
+*.pyc
+*.pyo

lightrace-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+        types_or: [python, pyi]

lightrace-0.1.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Unified `@trace` decorator for all observation types (span, generation, tool, chain, event)
+- Batch exporter compatible with Langfuse v3 ingestion format
+- Remote tool invocation via WebSocket (HMAC-SHA256 signed)
+- Context propagation via `contextvars` (thread-safe, async-safe)
+- Auto-generated JSON Schema from function type hints

lightrace-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to lightrace-python
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Quick Start
+
+```bash
+git clone https://github.com/SKE-Labs/lightrace-python.git
+cd lightrace-python
+uv sync --extra dev
+uv run pre-commit install
+```
+
+### Commands
+
+```bash
+# Testing
+uv run pytest -s -v tests/
+
+# Linting & formatting
+uv run ruff check .
+uv run ruff format .
+
+# Type checking
+uv run mypy src/lightrace
+
+# Pre-commit (all checks)
+uv run pre-commit run --all-files
+```
+
+## Code Quality
+
+### Pre-commit Hooks
+
+After `pre-commit install`, hooks run automatically on commit:
+- **ruff-check**: Linter with auto-fix
+- **ruff-format**: Code formatter
+
+### Style Guide
+
+- **Ruff** for linting and formatting (100 char line length)
+- **MyPy** with strict mode for type checking
+- Type hints required on all function definitions
+- Use `from __future__ import annotations` for modern type syntax
+
+### Testing
+
+We use **pytest** for testing. Tests live in `tests/`.
+
+```bash
+# Run all tests
+pytest -s -v tests/
+
+# Run specific test
+pytest -s -v tests/test_trace.py::TestTraceDecorator::test_root_trace
+```
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch
+2. Write tests for new functionality
+3. Ensure `pytest`, `ruff check .`, and `mypy src/lightrace` pass
+4. Submit a PR with a clear description
+
+## Release Process
+
+Releases are automated via GitHub Actions. Maintainers trigger the release workflow which handles versioning, building, and PyPI publishing via OIDC.
+
+## License
+
+MIT

lightrace-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lightrace Contributors
+
+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.

lightrace-0.1.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: lightrace
+Version: 0.1.1
+Summary: Lightweight LLM tracing SDK with remote tool invocation
+Project-URL: Repository, https://github.com/SKE-Labs/lightrace-python
+Project-URL: Changelog, https://github.com/SKE-Labs/lightrace-python/blob/main/CHANGELOG.md
+Author: Lightrace Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langfuse,llm,observability,opentelemetry,tool-invocation,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: websockets<17,>=13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# lightrace-python
+
+Lightweight LLM tracing SDK for Python with remote tool invocation.
+
+## Install
+
+```bash
+pip install lightrace
+```
+
+## Quick Start
+
+```python
+from lightrace import Lightrace, trace
+
+lt = Lightrace(
+    public_key="pk-lt-demo",
+    secret_key="sk-lt-demo",
+    host="http://localhost:3002",
+)
+
+# Root trace
+@trace()
+def run_agent(query: str):
+    return search(query)
+
+# Span
+@trace(type="span")
+def search(query: str) -> list:
+    return ["result1", "result2"]
+
+# Generation (LLM call)
+@trace(type="generation", model="gpt-4o")
+def generate(prompt: str) -> str:
+    return "LLM response"
+
+# Tool — remotely invocable from the Lightrace UI
+@trace(type="tool")
+def weather_lookup(city: str) -> dict:
+    return {"temp": 72, "unit": "F"}
+
+# Tool — traced but NOT remotely invocable
+@trace(type="tool", invoke=False)
+def read_file(path: str) -> str:
+    return open(path).read()
+
+run_agent("hello")
+lt.flush()
+lt.shutdown()
+```
+
+## `@trace` API
+
+```python
+@trace()                                    # Root trace
+@trace(type="span")                         # Span observation
+@trace(type="generation", model="gpt-4o")   # LLM generation
+@trace(type="tool")                         # Tool (remotely invocable)
+@trace(type="tool", invoke=False)           # Tool (trace only)
+```
+
+### Parameters
+
+| Parameter  | Type   | Default | Description                                              |
+| ---------- | ------ | ------- | -------------------------------------------------------- |
+| `type`     | `str`  | `None`  | `"span"`, `"generation"`, `"tool"`, `"chain"`, `"event"` |
+| `name`     | `str`  | `None`  | Override name (defaults to function name)                 |
+| `invoke`   | `bool` | `True`  | For `type="tool"`: register for remote invocation        |
+| `model`    | `str`  | `None`  | For `type="generation"`: LLM model name                  |
+| `metadata` | `dict` | `None`  | Static metadata attached to every call                   |
+
+## Compatibility
+
+Lightrace server also accepts traces from Langfuse Python/JS SDKs.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pre-commit install
+uv run pytest -s -v tests/
+uv run ruff check .
+uv run mypy src/lightrace
+```
+
+## License
+
+MIT

lightrace-0.1.1/README.md

@@ -0,0 +1,88 @@
+# lightrace-python
+
+Lightweight LLM tracing SDK for Python with remote tool invocation.
+
+## Install
+
+```bash
+pip install lightrace
+```
+
+## Quick Start
+
+```python
+from lightrace import Lightrace, trace
+
+lt = Lightrace(
+    public_key="pk-lt-demo",
+    secret_key="sk-lt-demo",
+    host="http://localhost:3002",
+)
+
+# Root trace
+@trace()
+def run_agent(query: str):
+    return search(query)
+
+# Span
+@trace(type="span")
+def search(query: str) -> list:
+    return ["result1", "result2"]
+
+# Generation (LLM call)
+@trace(type="generation", model="gpt-4o")
+def generate(prompt: str) -> str:
+    return "LLM response"
+
+# Tool — remotely invocable from the Lightrace UI
+@trace(type="tool")
+def weather_lookup(city: str) -> dict:
+    return {"temp": 72, "unit": "F"}
+
+# Tool — traced but NOT remotely invocable
+@trace(type="tool", invoke=False)
+def read_file(path: str) -> str:
+    return open(path).read()
+
+run_agent("hello")
+lt.flush()
+lt.shutdown()
+```
+
+## `@trace` API
+
+```python
+@trace()                                    # Root trace
+@trace(type="span")                         # Span observation
+@trace(type="generation", model="gpt-4o")   # LLM generation
+@trace(type="tool")                         # Tool (remotely invocable)
+@trace(type="tool", invoke=False)           # Tool (trace only)
+```
+
+### Parameters
+
+| Parameter  | Type   | Default | Description                                              |
+| ---------- | ------ | ------- | -------------------------------------------------------- |
+| `type`     | `str`  | `None`  | `"span"`, `"generation"`, `"tool"`, `"chain"`, `"event"` |
+| `name`     | `str`  | `None`  | Override name (defaults to function name)                 |
+| `invoke`   | `bool` | `True`  | For `type="tool"`: register for remote invocation        |
+| `model`    | `str`  | `None`  | For `type="generation"`: LLM model name                  |
+| `metadata` | `dict` | `None`  | Static metadata attached to every call                   |
+
+## Compatibility
+
+Lightrace server also accepts traces from Langfuse Python/JS SDKs.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pre-commit install
+uv run pytest -s -v tests/
+uv run ruff check .
+uv run mypy src/lightrace
+```
+
+## License
+
+MIT

lightrace-0.1.1/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lightrace"
+version = "0.1.1"
+description = "Lightweight LLM tracing SDK with remote tool invocation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Lightrace Contributors" }]
+keywords = ["llm", "tracing", "observability", "langfuse", "opentelemetry", "tool-invocation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "websockets>=13,<17",
+    "pydantic>=2,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/SKE-Labs/lightrace-python"
+Changelog = "https://github.com/SKE-Labs/lightrace-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.22",
+    "ruff>=0.15",
+    "mypy>=1.0",
+    "pre-commit>=3.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lightrace"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+log_cli = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+show_error_codes = true
+show_column_numbers = true
+
+[[tool.mypy.overrides]]
+module = ["websockets.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["langchain_core.*"]
+ignore_missing_imports = true

lightrace-0.1.1/src/lightrace/__init__.py

@@ -0,0 +1,8 @@
+"""Lightrace — lightweight LLM tracing SDK with remote tool invocation."""
+
+from .client import Lightrace
+from .observation import Observation
+from .trace import trace
+from .version import __version__
+
+__all__ = ["Lightrace", "Observation", "trace", "__version__"]