verica-observability 0.1.1__tar.gz

verica_observability-0.1.1/.gitignore

@@ -0,0 +1,40 @@
+# deps
+node_modules/
+.pnpm-store/
+
+# python sdk
+sdks/python/.venv/
+sdks/**/__pycache__/
+
+# test coverage
+coverage/
+
+# build output
+dist/
+.next/
+out/
+*.tsbuildinfo
+
+# turbo
+.turbo/
+
+# env / secrets
+.env
+.env.*
+!.env.example
+# key material (RSA credential keypair, etc.) — must never be committed; the
+# real values live base64-encoded in .env (and prod secret stores).
+*.pem
+
+# logs
+*.log
+npm-debug.log*
+
+# os / editor
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# drizzle local
+packages/db/drizzle/meta/_journal.bak

verica_observability-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: verica-observability
+Version: 0.1.1
+Summary: Two-line LLM tracing for Verica: init(token) and your OpenAI/Anthropic calls land as evaluable traces.
+Project-URL: Homepage, https://verica.app
+License-Expression: MIT
+Keywords: evals,llm,observability,opentelemetry,tracing,verica
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.33
+Requires-Dist: opentelemetry-instrumentation-openai>=0.33
+Requires-Dist: opentelemetry-sdk>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# verica-observability
+
+Two-line LLM tracing for [Verica](https://verica.app): your OpenAI/Anthropic
+calls land as evaluable traces.
+
+## Install
+
+```bash
+pip install verica-observability
+```
+
+## Use
+
+```python
+import verica
+
+verica.init(token=os.environ["VERICA_TOKEN"])
+
+# Import AFTER init so the client is patched.
+from openai import OpenAI
+```
+
+## Serverless
+
+Call `verica.flush()` (or `verica.shutdown()`) before the runtime freezes so
+the span batch is exported.
+
+## Options
+
+| Option / env var                             | Default    | Notes                           |
+| -------------------------------------------- | ---------- | ------------------------------- |
+| `token` / `VERICA_TOKEN`                     | (required) | ingest-scoped API token         |
+| `capture_content` / `VERICA_CAPTURE_CONTENT` | `true`     | send prompt/response content    |
+| `conversation_id`                            | (none)     | stamps `gen_ai.conversation.id` |
+| `service_name` / `OTEL_SERVICE_NAME`         | `app`      | resource service.name           |
+| `debug` / `VERICA_DEBUG`                     | `false`    | log export errors               |
+
+Fail-open by design: if Verica is unreachable or the token is invalid, spans are
+dropped and your app is never affected. Export errors are silent unless `debug`
+is on.

verica_observability-0.1.1/README.md

@@ -0,0 +1,40 @@
+# verica-observability
+
+Two-line LLM tracing for [Verica](https://verica.app): your OpenAI/Anthropic
+calls land as evaluable traces.
+
+## Install
+
+```bash
+pip install verica-observability
+```
+
+## Use
+
+```python
+import verica
+
+verica.init(token=os.environ["VERICA_TOKEN"])
+
+# Import AFTER init so the client is patched.
+from openai import OpenAI
+```
+
+## Serverless
+
+Call `verica.flush()` (or `verica.shutdown()`) before the runtime freezes so
+the span batch is exported.
+
+## Options
+
+| Option / env var                             | Default    | Notes                           |
+| -------------------------------------------- | ---------- | ------------------------------- |
+| `token` / `VERICA_TOKEN`                     | (required) | ingest-scoped API token         |
+| `capture_content` / `VERICA_CAPTURE_CONTENT` | `true`     | send prompt/response content    |
+| `conversation_id`                            | (none)     | stamps `gen_ai.conversation.id` |
+| `service_name` / `OTEL_SERVICE_NAME`         | `app`      | resource service.name           |
+| `debug` / `VERICA_DEBUG`                     | `false`    | log export errors               |
+
+Fail-open by design: if Verica is unreachable or the token is invalid, spans are
+dropped and your app is never affected. Export errors are silent unless `debug`
+is on.

verica_observability-0.1.1/examples/basic.py

@@ -0,0 +1,26 @@
+# Run from the repo (worker/web running, OPENAI_API_KEY + VERICA_TOKEN set):
+#   ./sdks/python/.venv/bin/pip install openai
+#   ./sdks/python/.venv/bin/python sdks/python/examples/basic.py
+import os
+
+import verica
+
+ok = verica.init(
+    token=os.environ.get("VERICA_TOKEN"),
+    endpoint=os.environ.get("VERICA_ENDPOINT", "http://localhost:3000"),
+    service_name="verica-example-python",
+    conversation_id="verica-sdk-check-python",
+)
+if not ok:
+    raise SystemExit(1)
+
+# Import AFTER init so the instrumentation patches the client.
+from openai import OpenAI  # noqa: E402
+
+client = OpenAI()
+res = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": 'Say "verica sdk check python" and nothing else.'}],
+)
+print(res.choices[0].message.content)
+verica.shutdown()  # drain the batch before the process exits

verica_observability-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "verica-observability"
+version = "0.1.1"
+description = "Two-line LLM tracing for Verica: init(token) and your OpenAI/Anthropic calls land as evaluable traces."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["verica", "observability", "opentelemetry", "llm", "tracing", "evals"]
+dependencies = [
+  "opentelemetry-sdk>=1.27",
+  "opentelemetry-exporter-otlp-proto-http>=1.27",
+  "opentelemetry-instrumentation-openai>=0.33",
+  "opentelemetry-instrumentation-anthropic>=0.33",
+]
+
+[project.urls]
+Homepage = "https://verica.app"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["verica"]
+
+[tool.ruff]
+line-length = 100

verica_observability-0.1.1/tests/test_config.py

@@ -0,0 +1,63 @@
+from verica._config import resolve_config
+
+
+def test_resolves_from_options():
+    cfg, missing = resolve_config({"token": "vk_1", "endpoint": "https://x.app"}, {})
+    assert missing == []
+    assert cfg.token == "vk_1"
+    assert cfg.endpoint == "https://x.app"
+    assert cfg.capture_content is True
+    assert cfg.service_name == "app"
+    assert cfg.debug is False
+
+
+def test_env_fallback_and_trailing_slash():
+    cfg, missing = resolve_config(
+        {}, {"VERICA_TOKEN": "vk_2", "VERICA_ENDPOINT": "https://x.app/"}
+    )
+    assert missing == []
+    assert cfg.endpoint == "https://x.app"
+
+
+def test_options_win_over_env():
+    cfg, _ = resolve_config(
+        {"token": "opt", "endpoint": "https://opt.app"},
+        {"VERICA_TOKEN": "env", "VERICA_ENDPOINT": "https://env.app"},
+    )
+    assert cfg.token == "opt"
+
+
+def test_missing_token_reported_not_raised():
+    cfg, missing = resolve_config({}, {})
+    assert cfg is None
+    assert missing == ["token"]
+
+
+def test_endpoint_defaults_to_hosted_ingest():
+    cfg, missing = resolve_config({"token": "t"}, {})
+    assert missing == []
+    assert cfg.endpoint == "https://ingest.verica.app"
+
+
+def test_endpoint_option_and_env_override_the_default():
+    cfg, _ = resolve_config({"token": "t", "endpoint": "http://localhost:3001"}, {})
+    assert cfg.endpoint == "http://localhost:3001"
+    cfg, _ = resolve_config({"token": "t"}, {"VERICA_ENDPOINT": "http://localhost:3001"})
+    assert cfg.endpoint == "http://localhost:3001"
+
+
+def test_capture_content_env_off_and_option_override():
+    base = {"token": "t", "endpoint": "https://x"}
+    cfg, _ = resolve_config(base, {"VERICA_CAPTURE_CONTENT": "false"})
+    assert cfg.capture_content is False
+    cfg, _ = resolve_config({**base, "capture_content": True}, {"VERICA_CAPTURE_CONTENT": "false"})
+    assert cfg.capture_content is True
+
+
+def test_debug_and_service_name_fallbacks():
+    cfg, _ = resolve_config(
+        {"token": "t", "endpoint": "https://x"},
+        {"VERICA_DEBUG": "1", "OTEL_SERVICE_NAME": "my-svc"},
+    )
+    assert cfg.debug is True
+    assert cfg.service_name == "my-svc"

verica_observability-0.1.1/tests/test_sdk.py

@@ -0,0 +1,25 @@
+import verica
+
+
+def teardown_function():
+    verica.shutdown()
+
+
+def test_init_without_config_is_noop_false(monkeypatch):
+    monkeypatch.delenv("VERICA_TOKEN", raising=False)
+    monkeypatch.delenv("VERICA_ENDPOINT", raising=False)
+    assert verica.init() is False
+
+
+def test_init_is_idempotent_and_fail_open():
+    # Unreachable endpoint: init must still succeed (batch export is async).
+    assert verica.init(token="vk_t", endpoint="http://127.0.0.1:9") is True
+    assert verica.init(token="vk_t", endpoint="http://127.0.0.1:9") is True
+
+
+def test_flush_and_shutdown_never_raise():
+    verica.flush()
+    verica.shutdown()
+    verica.init(token="vk_t", endpoint="http://127.0.0.1:9")
+    verica.flush()
+    verica.shutdown()

verica_observability-0.1.1/verica/__init__.py

@@ -0,0 +1,6 @@
+"""Two-line LLM tracing for Verica."""
+
+from verica._sdk import flush, init, shutdown
+
+__version__ = "0.1.1"
+__all__ = ["init", "flush", "shutdown"]

verica_observability-0.1.1/verica/_config.py

@@ -0,0 +1,50 @@
+"""Config resolution: options > env vars > defaults. Pure and import-safe."""
+
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+
+@dataclass(frozen=True)
+class Config:
+    token: str
+    endpoint: str
+    capture_content: bool
+    conversation_id: Optional[str]
+    service_name: str
+    debug: bool
+
+
+# Verica's hosted ingest endpoint. Override via the `endpoint` option or the
+# VERICA_ENDPOINT env var for self-host or local dev. Only `token` is required.
+DEFAULT_ENDPOINT = "https://ingest.verica.app"
+
+
+def _truthy(value: Optional[str]) -> bool:
+    return value in ("1", "true")
+
+
+def resolve_config(options: dict, env: Mapping[str, str]) -> "tuple[Optional[Config], list[str]]":
+    token = options.get("token") or env.get("VERICA_TOKEN") or ""
+    if not token:
+        return None, ["token"]
+
+    raw_endpoint = options.get("endpoint") or env.get("VERICA_ENDPOINT") or DEFAULT_ENDPOINT
+
+    capture = options.get("capture_content")
+    if capture is None:
+        raw = env.get("VERICA_CAPTURE_CONTENT")
+        capture = _truthy(raw) if raw is not None else True
+
+    return (
+        Config(
+            token=token,
+            endpoint=raw_endpoint.rstrip("/"),
+            capture_content=capture,
+            conversation_id=options.get("conversation_id"),
+            service_name=options.get("service_name") or env.get("OTEL_SERVICE_NAME") or "app",
+            debug=options.get("debug")
+            if options.get("debug") is not None
+            else _truthy(env.get("VERICA_DEBUG")),
+        ),
+        [],
+    )

verica_observability-0.1.1/verica/_sdk.py

@@ -0,0 +1,116 @@
+"""Fail-open OTel setup: never raise into the host app."""
+
+import logging
+import os
+
+from verica._config import Config, resolve_config
+
+logger = logging.getLogger("verica")
+
+_provider = None  # type: ignore[var-annotated]
+
+
+class _ConversationIdProcessor:
+    """Stamps gen_ai.conversation.id on every span (Phase 4 session join)."""
+
+    def __init__(self, conversation_id: str):
+        self._id = conversation_id
+
+    def on_start(self, span, parent_context=None):
+        span.set_attribute("gen_ai.conversation.id", self._id)
+
+    def on_end(self, span):
+        pass
+
+    def shutdown(self):
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000):
+        return True
+
+
+def init(**options) -> bool:
+    global _provider
+    if _provider is not None:
+        logger.warning("verica.init() called twice; ignoring the second call.")
+        return True
+
+    cfg, missing = resolve_config(options, os.environ)
+    if cfg is None:
+        logger.warning("verica: missing %s; tracing is disabled.", " and ".join(missing))
+        return False
+
+    try:
+        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
+
+        # openllmetry instrumentations gate content capture on this env var.
+        os.environ.setdefault("TRACELOOP_TRACE_CONTENT", str(cfg.capture_content).lower())
+
+        # Spec §5: export errors (401, network) must not spam the host app's
+        # logs; the OTLP exporter logs through this logger on every failure.
+        if not cfg.debug:
+            logging.getLogger("opentelemetry.exporter.otlp.proto.http.trace_exporter").setLevel(
+                logging.CRITICAL
+            )
+            logging.getLogger("opentelemetry.sdk.trace.export").setLevel(logging.CRITICAL)
+
+        provider = TracerProvider(resource=Resource.create({SERVICE_NAME: cfg.service_name}))
+        if cfg.conversation_id:
+            provider.add_span_processor(_ConversationIdProcessor(cfg.conversation_id))
+        provider.add_span_processor(
+            BatchSpanProcessor(
+                OTLPSpanExporter(
+                    endpoint=f"{cfg.endpoint}/v1/traces",
+                    headers={"Authorization": f"Bearer {cfg.token}"},
+                )
+            )
+        )
+        trace.set_tracer_provider(provider)
+        _instrument(provider, cfg)
+        _provider = provider
+        return True
+    except Exception as err:  # noqa: BLE001 - fail-open by contract
+        logger.warning("verica: init failed; tracing is disabled. %s", err if cfg.debug else "")
+        _provider = None
+        return False
+
+
+def _instrument(provider, cfg: Config) -> None:
+    """Each instrumentor is optional: a missing/broken one never blocks init."""
+    try:
+        from opentelemetry.instrumentation.openai import OpenAIInstrumentor
+
+        OpenAIInstrumentor().instrument(tracer_provider=provider)
+    except Exception as err:  # noqa: BLE001
+        if cfg.debug:
+            logger.warning("verica: openai instrumentation not active: %s", err)
+    try:
+        from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+
+        AnthropicInstrumentor().instrument(tracer_provider=provider)
+    except Exception as err:  # noqa: BLE001
+        if cfg.debug:
+            logger.warning("verica: anthropic instrumentation not active: %s", err)
+
+
+def flush() -> None:
+    try:
+        if _provider is not None:
+            _provider.force_flush()
+    except Exception:  # noqa: BLE001
+        logger.debug("verica: flush failed", exc_info=True)
+
+
+def shutdown() -> None:
+    global _provider
+    try:
+        if _provider is not None:
+            _provider.shutdown()
+    except Exception:  # noqa: BLE001
+        logger.debug("verica: shutdown failed", exc_info=True)
+    finally:
+        _provider = None