custodia-sdk 0.1.0__tar.gz

custodia_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2026 Neurona. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of Neurona ("Licensor"). The Software is made available
+for download and inspection only. No license, right, or permission to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software is granted except as expressly agreed in a separate written
+commercial license agreement with Licensor.
+
+Use of the Software without a valid, active commercial license from Licensor
+is strictly prohibited.
+
+To obtain a commercial license, contact: michael.gunawan2002@gmail.com
+
+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.

custodia_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: custodia-sdk
+Version: 0.1.0
+Summary: Custodia tracing SDK
+Author: ssabrut
+Author-email: ssabrut <michael.gunawan2002@gmail.com>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.44.0
+Requires-Dist: opentelemetry-sdk>=1.44.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# custodia-sdk
+
+Python tracing SDK for Custodia. Instruments function calls as OpenTelemetry
+spans and exports them via OTLP/HTTP.
+
+> **License:** proprietary. Use requires a paid commercial license from
+> Neurona. See [LICENSE](./LICENSE). Contact michael.gunawan2002@gmail.com
+> to obtain one.
+
+## Install
+
+```bash
+pip install custodia-sdk
+# or
+uv add custodia-sdk
+```
+
+## Configuration
+
+Set via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `CUSTODIA_INGEST_URL` | OTLP/HTTP traces endpoint | `http://localhost:4318/v1/traces` |
+| `CUSTODIA_API_KEY` | Bearer token sent with exported spans | *(none)* |
+| `CUSTODIA_SERVICE_NAME` | `service.name` resource attribute | `unknown-service` |
+
+## Usage
+
+```python
+from custodia import trace, trace_async, trace_span, atrace_span
+
+@trace(name="fetch_user", metadata={"component": "db"})
+def get_user(user_id: str):
+    return db.query(user_id)
+
+@trace_async(name="call_llm")
+async def generate(prompt: str) -> str:
+    return await llm_client.complete(prompt)
+
+with trace_span("parse_response") as span:
+    data = json.loads(raw)
+    span.set_attribute("record_count", len(data))
+
+async with atrace_span("call_downstream") as span:
+    resp = await http_client.get(url)
+    span.set_attribute("http.status_code", resp.status_code)
+```
+
+- `trace` / `trace_async`: decorators that auto-capture args/return value as
+  `gen_ai.prompt` / `gen_ai.completion` span attributes.
+- `trace_span` / `atrace_span`: context managers for manual span control,
+  no automatic I/O capture.

custodia_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# custodia-sdk
+
+Python tracing SDK for Custodia. Instruments function calls as OpenTelemetry
+spans and exports them via OTLP/HTTP.
+
+> **License:** proprietary. Use requires a paid commercial license from
+> Neurona. See [LICENSE](./LICENSE). Contact michael.gunawan2002@gmail.com
+> to obtain one.
+
+## Install
+
+```bash
+pip install custodia-sdk
+# or
+uv add custodia-sdk
+```
+
+## Configuration
+
+Set via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `CUSTODIA_INGEST_URL` | OTLP/HTTP traces endpoint | `http://localhost:4318/v1/traces` |
+| `CUSTODIA_API_KEY` | Bearer token sent with exported spans | *(none)* |
+| `CUSTODIA_SERVICE_NAME` | `service.name` resource attribute | `unknown-service` |
+
+## Usage
+
+```python
+from custodia import trace, trace_async, trace_span, atrace_span
+
+@trace(name="fetch_user", metadata={"component": "db"})
+def get_user(user_id: str):
+    return db.query(user_id)
+
+@trace_async(name="call_llm")
+async def generate(prompt: str) -> str:
+    return await llm_client.complete(prompt)
+
+with trace_span("parse_response") as span:
+    data = json.loads(raw)
+    span.set_attribute("record_count", len(data))
+
+async with atrace_span("call_downstream") as span:
+    resp = await http_client.get(url)
+    span.set_attribute("http.status_code", resp.status_code)
+```
+
+- `trace` / `trace_async`: decorators that auto-capture args/return value as
+  `gen_ai.prompt` / `gen_ai.completion` span attributes.
+- `trace_span` / `atrace_span`: context managers for manual span control,
+  no automatic I/O capture.

custodia_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "custodia-sdk"
+version = "0.1.0"
+description = "Custodia tracing SDK"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [
+    { name = "ssabrut", email = "michael.gunawan2002@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "opentelemetry-exporter-otlp-proto-http>=1.44.0",
+    "opentelemetry-sdk>=1.44.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[tool.uv.build-backend]
+module-name = "custodia"
+
+[build-system]
+requires = ["uv_build>=0.11.30,<0.12.0"]
+build-backend = "uv_build"

custodia_sdk-0.1.0/src/custodia/__init__.py

@@ -0,0 +1,4 @@
+from ._tracer import get_tracer
+from .trace import atrace_span, trace, trace_async, trace_span
+
+__all__ = ["trace", "trace_async", "trace_span", "atrace_span", "get_tracer"]

custodia_sdk-0.1.0/src/custodia/_tracer.py

@@ -0,0 +1,36 @@
+import os
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+_initialized = False
+
+
+def _ensure_initialized() -> None:
+    global _initialized
+    if _initialized:
+        return
+
+    endpoint = os.environ.get("CUSTODIA_INGEST_URL", "http://localhost:4318/v1/traces")
+    api_key = os.environ.get("CUSTODIA_API_KEY", "")
+
+    provider = TracerProvider(
+        resource=Resource.create(
+            {"service.name": os.environ.get("CUSTODIA_SERVICE_NAME", "unknown-service")}
+        )
+    )
+    exporter = OTLPSpanExporter(
+        endpoint=endpoint,
+        headers={"Authorization": f"Bearer {api_key}"} if api_key else {},
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    otel_trace.set_tracer_provider(provider)
+    _initialized = True
+
+
+def get_tracer() -> otel_trace.Tracer:
+    _ensure_initialized()
+    return otel_trace.get_tracer("custodia-sdk")

custodia_sdk-0.1.0/src/custodia/trace.py

@@ -0,0 +1,237 @@
+import functools
+import json
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any, AsyncGenerator, Callable, Generator, Optional
+
+from opentelemetry.trace import Status, StatusCode
+
+from ._tracer import get_tracer
+
+GENAI_PROMPT_ATTR = "gen_ai.prompt"
+GENAI_COMPLETION_ATTR = "gen_ai.completion"
+
+
+def _set_io_attributes(span: Any, args: tuple, kwargs: dict, result: Any) -> None:
+    try:
+        span.set_attribute(
+            GENAI_PROMPT_ATTR,
+            json.dumps({"args": _safe_repr(args), "kwargs": _safe_repr(kwargs)}),
+        )
+        span.set_attribute(GENAI_COMPLETION_ATTR, _safe_repr(result))
+    except TypeError:
+        pass
+
+
+def _safe_repr(value: Any) -> str:
+    try:
+        return json.dumps(value, default=str)
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+def _set_span_metadata(span: Any, metadata: Optional[dict]) -> None:
+    if metadata:
+        for key, value in metadata.items():
+            span.set_attribute(f"metadata.{key}", _safe_repr(value))
+
+
+def _record_error(span: Any, exc: Exception) -> None:
+    span.set_status(Status(StatusCode.ERROR, str(exc)))
+    span.record_exception(exc)
+
+
+def trace(name: Optional[str] = None, metadata: Optional[dict] = None) -> Callable:
+    """Decorator that wraps a synchronous function in an OpenTelemetry span.
+
+    On each call, starts a span named `name` (or the function's `__name__`
+    if omitted), attaches `metadata` as `metadata.<key>` span attributes,
+    invokes the wrapped function, and records the call's arguments and
+    return value as `gen_ai.prompt` / `gen_ai.completion` span attributes
+    (JSON-encoded, falling back to `repr()` for non-serializable values).
+
+    If the wrapped function raises, the exception is recorded on the span,
+    the span status is set to ERROR, and the exception is re-raised
+    unchanged.
+
+    Use this for a whole function call that represents one logical
+    operation worth tracing (e.g. an LLM call), where capturing all
+    inputs/outputs automatically is desired. For tracing only part of a
+    function, or to control which attributes are recorded, use
+    `trace_span` instead.
+
+    Args:
+        name: Span name. Defaults to the decorated function's `__name__`.
+        metadata: Optional static key/value pairs attached to every span
+            created by this decorator, as `metadata.<key>` attributes.
+
+    Returns:
+        A decorator that wraps a sync function, preserving its signature
+        and return value via `functools.wraps`.
+
+    Example:
+    ```python
+    @trace(name="fetch_user", metadata={"component": "db"})
+    def get_user(user_id: str) -> User:
+        return db.query(user_id)
+    ```
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        span_name = name or fn.__name__
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = get_tracer()
+            with tracer.start_as_current_span(span_name) as span:
+                _set_span_metadata(span, metadata)
+                try:
+                    result = fn(*args, **kwargs)
+                except Exception as exc:
+                    _record_error(span, exc)
+                    raise
+                _set_io_attributes(span, args, kwargs, result)
+                return result
+
+        return wrapper
+
+    return decorator
+
+
+def trace_async(name: Optional[str] = None, metadata: Optional[dict] = None) -> Callable:
+    """Decorator that wraps an async function in an OpenTelemetry span.
+
+    Async counterpart to `trace`. Behaves identically — starts a span,
+    attaches `metadata`, awaits the wrapped coroutine function, records
+    its arguments and return value as `gen_ai.prompt` / `gen_ai.completion`
+    span attributes, and records/reraises any exception with the span
+    marked as ERROR — but wraps a coroutine function (`async def`) instead
+    of a plain function.
+
+    Args:
+        name: Span name. Defaults to the decorated function's `__name__`.
+        metadata: Optional static key/value pairs attached to every span
+            created by this decorator, as `metadata.<key>` attributes.
+
+    Returns:
+        A decorator that wraps an async function, preserving its signature
+        and return value via `functools.wraps`.
+
+    Example:
+    ```python
+    @trace_async(name="call_llm")
+    async def generate(prompt: str) -> str:
+        return await llm_client.complete(prompt)
+    ```
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        span_name = name or fn.__name__
+
+        @functools.wraps(fn)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = get_tracer()
+            with tracer.start_as_current_span(span_name) as span:
+                _set_span_metadata(span, metadata)
+                try:
+                    result = await fn(*args, **kwargs)
+                except Exception as exc:
+                    _record_error(span, exc)
+                    raise
+                _set_io_attributes(span, args, kwargs, result)
+                return result
+
+        return wrapper
+
+    return decorator
+
+
+@contextmanager
+def trace_span(
+    name: str, metadata: Optional[dict] = None
+) -> Generator[Any, None, None]:
+    """Context manager that starts an OpenTelemetry span around a block of
+    synchronous code.
+
+    Starts a span named `name`, attaches `metadata` as `metadata.<key>`
+    span attributes, and yields the span object to the caller for manual
+    attribute/event setting. Unlike `trace`, no automatic prompt/completion
+    (input/output) attributes are recorded — the caller has full control
+    over what gets attached to the span.
+
+    If an exception propagates out of the `with` block, it is recorded on
+    the span, the span status is set to ERROR, and the exception is
+    re-raised unchanged.
+
+    Use this instead of `trace` when only part of a function should be
+    traced, when a single function performs multiple distinct operations
+    that each deserve their own span, when tracing code with no dedicated
+    function to decorate, or when automatic capture of args/return values
+    is undesirable (e.g. large or sensitive payloads).
+
+    Args:
+        name: Span name.
+        metadata: Optional key/value pairs attached to the span as
+            `metadata.<key>` attributes.
+
+    Yields:
+        The active span object, for setting custom attributes
+        (`span.set_attribute(...)`) or recording events during the block.
+
+    Example:
+    ```python
+    with trace_span("parse_response", metadata={"format": "json"}) as span:
+        data = json.loads(raw)
+        span.set_attribute("record_count", len(data))
+    ```
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name) as span:
+        _set_span_metadata(span, metadata)
+        try:
+            yield span
+        except Exception as exc:
+            _record_error(span, exc)
+            raise
+
+
+@asynccontextmanager
+async def atrace_span(
+    name: str, metadata: Optional[dict] = None
+) -> AsyncGenerator[Any, None]:
+    """Async context manager that starts an OpenTelemetry span around a
+    block of async code.
+
+    Async counterpart to `trace_span`. Starts a span named `name`, attaches
+    `metadata` as `metadata.<key>` span attributes, and yields the span
+    object for manual attribute setting inside an `async with` block. No
+    automatic prompt/completion attributes are recorded — same
+    caller-controlled attribution as `trace_span`.
+
+    If an exception propagates out of the `async with` block, it is
+    recorded on the span, the span status is set to ERROR, and the
+    exception is re-raised unchanged.
+
+    Args:
+        name: Span name.
+        metadata: Optional key/value pairs attached to the span as
+            `metadata.<key>` attributes.
+
+    Yields:
+        The active span object, for setting custom attributes
+        (`span.set_attribute(...)`) or recording events during the block.
+
+    Example:
+    ```python
+    async with atrace_span("call_downstream") as span:
+        resp = await http_client.get(url)
+        span.set_attribute("http.status_code", resp.status_code)
+    ```
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name) as span:
+        _set_span_metadata(span, metadata)
+        try:
+            yield span
+        except Exception as exc:
+            _record_error(span, exc)
+            raise