bryel 0.1.0__tar.gz

bryel-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/

bryel-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: bryel
+Version: 0.1.0
+Summary: OpenTelemetry-native tracing for LLM apps and agents — ships OpenInference/OTLP traces to bryel.
+Project-URL: Homepage, https://docs.bryel.ai
+Project-URL: Documentation, https://docs.bryel.ai
+Author: bryel
+License-Expression: MIT
+Keywords: bryel,genai,llm,observability,openinference,opentelemetry,tracing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Provides-Extra: anthropic
+Requires-Dist: openinference-instrumentation-anthropic; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: openinference-instrumentation-bedrock; extra == 'bedrock'
+Provides-Extra: langchain
+Requires-Dist: openinference-instrumentation-langchain; extra == 'langchain'
+Provides-Extra: llama-index
+Requires-Dist: openinference-instrumentation-llama-index; extra == 'llama-index'
+Provides-Extra: openai
+Requires-Dist: openinference-instrumentation-openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# bryel (Python)
+
+OpenTelemetry-native tracing for LLM apps and agents. One call ships your model
+calls, tool calls, tokens, and cost to [bryel](https://docs.bryel.ai) as
+OpenInference traces — from any framework.
+
+```bash
+uv add bryel            # or: pip install bryel
+```
+
+## Quickstart
+
+```python
+import bryel
+bryel.init(api_key="bk_…", service_name="my-app")
+
+# Trace OpenAI (any OpenInference instrumentor works the same way):
+from openinference.instrumentation.openai import OpenAIInstrumentor
+OpenAIInstrumentor().instrument()
+
+from openai import OpenAI
+OpenAI().chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "hello"}],
+)
+```
+
+Prefer bryel to wire up everything it can find? Let it instrument every installed
+OpenInference library for you:
+
+```python
+import bryel
+bryel.init(api_key="bk_…", instrument=True)   # instruments openai, anthropic, langchain, …
+```
+
+## How it works
+
+bryel is just the exporter. It configures an OpenTelemetry `TracerProvider` with
+an OTLP/HTTP exporter pointed at the bryel ingest, authenticated with your API
+key. The [OpenInference instrumentors](https://github.com/Arize-ai/openinference)
+emit the spans; bryel's ingest normalizes both the OpenInference (`llm.*`) and
+OpenTelemetry GenAI (`gen_ai.*`) conventions — so there's nothing to map.
+
+## API
+
+### `bryel.init(api_key=None, *, service_name=None, endpoint=None, headers=None, set_global=True, instrument=False)`
+
+Configures the exporter and returns the `TracerProvider`.
+
+- `api_key` — your project API key (`bk_…`). Falls back to `$BRYEL_KEY`.
+- `service_name` — OpenTelemetry `service.name`.
+- `endpoint` — OTLP/HTTP traces URL. Defaults to the bryel ingest, or
+  `$BRYEL_INGEST_URL` for self-hosting.
+- `headers` — extra headers, merged after auth.
+- `set_global` — register as the global OTel provider (default `True`).
+- `instrument` — also auto-instrument installed OpenInference libraries.
+
+### `bryel.auto_instrument(tracer_provider=None) -> list[str]`
+
+Best-effort instrument every installed OpenInference library. Returns the ones it
+wired up. Safe to call with none installed.
+
+### `bryel.shutdown()`
+
+Flush pending spans and shut down. Call on process exit.
+
+## Feedback and grouping
+
+Group turns into a conversation and attach 👍/👎 by stamping metadata on your
+spans — set `session.id`, `user.id`, and a `bryel.interaction.id` you mint. See
+the [docs](https://docs.bryel.ai).
+
+MIT © bryel

bryel-0.1.0/README.md

@@ -0,0 +1,73 @@
+# bryel (Python)
+
+OpenTelemetry-native tracing for LLM apps and agents. One call ships your model
+calls, tool calls, tokens, and cost to [bryel](https://docs.bryel.ai) as
+OpenInference traces — from any framework.
+
+```bash
+uv add bryel            # or: pip install bryel
+```
+
+## Quickstart
+
+```python
+import bryel
+bryel.init(api_key="bk_…", service_name="my-app")
+
+# Trace OpenAI (any OpenInference instrumentor works the same way):
+from openinference.instrumentation.openai import OpenAIInstrumentor
+OpenAIInstrumentor().instrument()
+
+from openai import OpenAI
+OpenAI().chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "hello"}],
+)
+```
+
+Prefer bryel to wire up everything it can find? Let it instrument every installed
+OpenInference library for you:
+
+```python
+import bryel
+bryel.init(api_key="bk_…", instrument=True)   # instruments openai, anthropic, langchain, …
+```
+
+## How it works
+
+bryel is just the exporter. It configures an OpenTelemetry `TracerProvider` with
+an OTLP/HTTP exporter pointed at the bryel ingest, authenticated with your API
+key. The [OpenInference instrumentors](https://github.com/Arize-ai/openinference)
+emit the spans; bryel's ingest normalizes both the OpenInference (`llm.*`) and
+OpenTelemetry GenAI (`gen_ai.*`) conventions — so there's nothing to map.
+
+## API
+
+### `bryel.init(api_key=None, *, service_name=None, endpoint=None, headers=None, set_global=True, instrument=False)`
+
+Configures the exporter and returns the `TracerProvider`.
+
+- `api_key` — your project API key (`bk_…`). Falls back to `$BRYEL_KEY`.
+- `service_name` — OpenTelemetry `service.name`.
+- `endpoint` — OTLP/HTTP traces URL. Defaults to the bryel ingest, or
+  `$BRYEL_INGEST_URL` for self-hosting.
+- `headers` — extra headers, merged after auth.
+- `set_global` — register as the global OTel provider (default `True`).
+- `instrument` — also auto-instrument installed OpenInference libraries.
+
+### `bryel.auto_instrument(tracer_provider=None) -> list[str]`
+
+Best-effort instrument every installed OpenInference library. Returns the ones it
+wired up. Safe to call with none installed.
+
+### `bryel.shutdown()`
+
+Flush pending spans and shut down. Call on process exit.
+
+## Feedback and grouping
+
+Group turns into a conversation and attach 👍/👎 by stamping metadata on your
+spans — set `session.id`, `user.id`, and a `bryel.interaction.id` you mint. See
+the [docs](https://docs.bryel.ai).
+
+MIT © bryel

bryel-0.1.0/examples/openai_chat.py

@@ -0,0 +1,23 @@
+"""Minimal example: trace an OpenAI call to bryel.
+
+    export BRYEL_KEY=bk_...          # your bryel project key
+    export OPENAI_API_KEY=sk-...     # your OpenAI key
+    uv run --with bryel[openai] --with openai examples/openai_chat.py
+"""
+
+import bryel
+
+# One call sets up the exporter (reads BRYEL_KEY) + instruments installed
+# OpenInference libraries (openai here).
+bryel.init(service_name="bryel-python-example", instrument=True)
+
+from openai import OpenAI  # noqa: E402
+
+resp = OpenAI().chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "In one sentence, what is an OpenTelemetry span?"}],
+)
+print(resp.choices[0].message.content)
+
+# Flush before exit so the span is delivered.
+bryel.shutdown()

bryel-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bryel"
+version = "0.1.0"
+description = "OpenTelemetry-native tracing for LLM apps and agents — ships OpenInference/OTLP traces to bryel."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "bryel" }]
+keywords = ["bryel", "llm", "tracing", "observability", "opentelemetry", "openinference", "genai"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "opentelemetry-api>=1.20.0",
+  "opentelemetry-sdk>=1.20.0",
+  "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+]
+
+[project.urls]
+Homepage = "https://docs.bryel.ai"
+Documentation = "https://docs.bryel.ai"
+
+# Convenience extras: pull in an OpenInference instrumentor for your stack.
+# You can also install any instrumentor yourself; bryel just exports the spans.
+[project.optional-dependencies]
+openai = ["openinference-instrumentation-openai"]
+anthropic = ["openinference-instrumentation-anthropic"]
+langchain = ["openinference-instrumentation-langchain"]
+llama-index = ["openinference-instrumentation-llama-index"]
+bedrock = ["openinference-instrumentation-bedrock"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bryel"]

bryel-0.1.0/src/bryel/__init__.py

@@ -0,0 +1,131 @@
+"""bryel — OpenTelemetry-native tracing for LLM apps and agents.
+
+One call configures OpenTelemetry to ship traces to bryel; then any
+OpenInference instrumentor (OpenAI, Anthropic, LangChain, LlamaIndex, …) flows
+through automatically:
+
+    import bryel
+    bryel.init(api_key="bk_…", service_name="my-app")
+
+    from openinference.instrumentation.openai import OpenAIInstrumentor
+    OpenAIInstrumentor().instrument()
+
+or let bryel instrument every installed OpenInference library for you:
+
+    bryel.init(api_key="bk_…", instrument=True)
+
+bryel's ingest normalizes both the OpenInference (`llm.*`, `openinference.*`) and
+OpenTelemetry GenAI (`gen_ai.*`) conventions, so there is nothing to map
+client-side — the SDK is just the exporter.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Mapping, Optional
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+__all__ = ["init", "auto_instrument", "shutdown", "DEFAULT_INGEST_ENDPOINT", "__version__"]
+
+__version__ = "0.1.0"
+
+#: OTLP/HTTP traces endpoint for the bryel SaaS ingest. The receiver stamps
+#: tenant/project from the API key server-side — the SDK never sends them.
+DEFAULT_INGEST_ENDPOINT = "https://ingest.eu.bryel.ai/v1/traces"
+
+# Common OpenInference instrumentors, tried in order by auto_instrument(). Each
+# is optional — missing ones are skipped, nothing is a hard dependency.
+_INSTRUMENTORS = [
+    ("openinference.instrumentation.openai", "OpenAIInstrumentor"),
+    ("openinference.instrumentation.anthropic", "AnthropicInstrumentor"),
+    ("openinference.instrumentation.langchain", "LangChainInstrumentor"),
+    ("openinference.instrumentation.llama_index", "LlamaIndexInstrumentor"),
+    ("openinference.instrumentation.bedrock", "BedrockInstrumentor"),
+    ("openinference.instrumentation.groq", "GroqInstrumentor"),
+    ("openinference.instrumentation.mistralai", "MistralAIInstrumentor"),
+    ("openinference.instrumentation.vertexai", "VertexAIInstrumentor"),
+]
+
+_provider: Optional[TracerProvider] = None
+
+
+def init(
+    api_key: Optional[str] = None,
+    *,
+    service_name: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    headers: Optional[Mapping[str, str]] = None,
+    set_global: bool = True,
+    instrument: bool = False,
+) -> TracerProvider:
+    """Configure OpenTelemetry to ship traces to bryel and return the provider.
+
+    Args:
+        api_key: your bryel project API key (``bk_…``). Falls back to the
+            ``BRYEL_KEY`` environment variable.
+        service_name: OpenTelemetry ``service.name`` for this app. Optional.
+        endpoint: OTLP/HTTP traces URL. Defaults to the bryel ingest, or the
+            ``BRYEL_INGEST_URL`` env var if set (for self-hosting).
+        headers: extra headers, merged after the auth header.
+        set_global: register the provider as the global OpenTelemetry provider
+            (so instrumentors pick it up automatically). Default True.
+        instrument: also auto-instrument every installed OpenInference library
+            (see :func:`auto_instrument`). Default False.
+
+    Returns:
+        The configured ``TracerProvider`` (keep it to call ``.shutdown()``).
+    """
+    global _provider
+
+    key = api_key or os.environ.get("BRYEL_KEY")
+    if not key:
+        raise ValueError("bryel.init: api_key is required (pass api_key=… or set BRYEL_KEY)")
+
+    resource = Resource.create({SERVICE_NAME: service_name} if service_name else {})
+    exporter = OTLPSpanExporter(
+        endpoint=endpoint or os.environ.get("BRYEL_INGEST_URL") or DEFAULT_INGEST_ENDPOINT,
+        headers={"Authorization": f"Bearer {key}", **(dict(headers) if headers else {})},
+    )
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    if set_global:
+        trace.set_tracer_provider(provider)
+    _provider = provider
+
+    if instrument:
+        auto_instrument(tracer_provider=provider)
+
+    return provider
+
+
+def auto_instrument(tracer_provider: Optional[TracerProvider] = None) -> List[str]:
+    """Best-effort: instrument every installed OpenInference library.
+
+    Safe to call whether or not any instrumentors are installed — missing ones
+    are skipped. Returns the names of the libraries that were instrumented.
+    """
+    instrumented: List[str] = []
+    kwargs = {"tracer_provider": tracer_provider} if tracer_provider is not None else {}
+    for module_name, class_name in _INSTRUMENTORS:
+        try:
+            module = __import__(module_name, fromlist=[class_name])
+            getattr(module, class_name)().instrument(**kwargs)
+            instrumented.append(class_name)
+        except Exception:
+            # not installed, or already instrumented — skip it
+            continue
+    return instrumented
+
+
+def shutdown() -> None:
+    """Flush pending spans and shut down the provider. Call on process exit."""
+    global _provider
+    if _provider is not None:
+        _provider.shutdown()
+        _provider = None

bryel-0.1.0/tests/test_bryel.py

@@ -0,0 +1,48 @@
+import pytest
+
+import bryel
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def test_default_endpoint_matches_ingest():
+    assert bryel.DEFAULT_INGEST_ENDPOINT == "https://ingest.eu.bryel.ai/v1/traces"
+
+
+def test_init_requires_key(monkeypatch):
+    monkeypatch.delenv("BRYEL_KEY", raising=False)
+    with pytest.raises(ValueError):
+        bryel.init()
+
+
+def test_init_returns_provider_and_traces(monkeypatch):
+    monkeypatch.delenv("BRYEL_KEY", raising=False)
+    provider = bryel.init(
+        api_key="bk_test",
+        service_name="unit-test",
+        endpoint="http://localhost:0/v1/traces",  # never actually flushed here
+        set_global=False,
+    )
+    assert isinstance(provider, TracerProvider)
+    # a tracer from the provider can start/end a span without error
+    span = provider.get_tracer("test").start_span("ping")
+    span.set_attribute("llm.model_name", "gpt-4o-mini")
+    span.end()
+    bryel.shutdown()
+
+
+def test_api_key_from_env(monkeypatch):
+    monkeypatch.setenv("BRYEL_KEY", "bk_env")
+    provider = bryel.init(set_global=False, endpoint="http://localhost:0/v1/traces")
+    assert isinstance(provider, TracerProvider)
+    bryel.shutdown()
+
+
+def test_auto_instrument_safe_with_none_installed():
+    # returns a list; skips libraries that aren't installed instead of raising
+    result = bryel.auto_instrument()
+    assert isinstance(result, list)
+
+
+def test_shutdown_is_idempotent():
+    bryel.shutdown()
+    bryel.shutdown()  # no-op, must not raise