traceotter 0.1.0__tar.gz

traceotter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Garakapati
+
+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.

traceotter-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: traceotter
+Version: 0.1.0
+Summary: Agent observability Python SDK for Traceotter
+Author: Nikhil Garakapati
+License: MIT
+Project-URL: Homepage, https://github.com/29m10/traceotter-python-sdk
+Project-URL: Repository, https://github.com/29m10/traceotter-python-sdk
+Keywords: traceotter,observability,agents,llm,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: pydantic<3.0,>=1.10
+Dynamic: license-file
+
+# Traceotter Python Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Traceotter%2FPython)
+[![pypi](https://img.shields.io/pypi/v/traceotter)](https://pypi.python.org/pypi/traceotter)
+
+The Traceotter Python library provides convenient access to the Traceotter APIs from Python.
+
+## Installation
+
+```sh
+pip install traceotter
+```
+
+## Usage
+
+Instantiate and use the client with the following:
+
+```python
+from traceotter import CreateAnnotationQueueRequest
+from traceotter.client import FernTraceotter
+
+client = FernTraceotter(
+    x_traceotter_sdk_name="YOUR_X_TRACEOTTER_SDK_NAME",
+    x_traceotter_sdk_version="YOUR_X_TRACEOTTER_SDK_VERSION",
+    x_traceotter_public_key="YOUR_X_TRACEOTTER_PUBLIC_KEY",
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    base_url="https://yourhost.com/path/to/api",
+)
+client.annotation_queues.create_queue(
+    request=CreateAnnotationQueueRequest(
+        name="name",
+        score_config_ids=["scoreConfigIds", "scoreConfigIds"],
+    ),
+)
+```
+
+## Async Client
+
+The SDK also exports an `async` client so that you can make non-blocking calls to our API.
+
+```python
+import asyncio
+
+from traceotter import CreateAnnotationQueueRequest
+from traceotter.client import AsyncFernTraceotter
+
+client = AsyncFernTraceotter(
+    x_traceotter_sdk_name="YOUR_X_TRACEOTTER_SDK_NAME",
+    x_traceotter_sdk_version="YOUR_X_TRACEOTTER_SDK_VERSION",
+    x_traceotter_public_key="YOUR_X_TRACEOTTER_PUBLIC_KEY",
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    base_url="https://yourhost.com/path/to/api",
+)
+
+
+async def main() -> None:
+    await client.annotation_queues.create_queue(
+        request=CreateAnnotationQueueRequest(
+            name="name",
+            score_config_ids=["scoreConfigIds", "scoreConfigIds"],
+        ),
+    )
+
+
+asyncio.run(main())
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```python
+from .api_error import ApiError
+
+try:
+    client.annotation_queues.create_queue(...)
+except ApiError as e:
+    print(e.status_code)
+    print(e.body)
+```
+
+## Advanced
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retriable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `max_retries` request option to configure this behavior.
+
+```python
+client.annotation_queues.create_queue(...,{
+    max_retries=1
+})
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
+
+```python
+
+from traceotter.client import FernTraceotter
+
+client = FernTraceotter(..., { timeout=20.0 }, )
+
+
+# Override timeout for a specific method
+client.annotation_queues.create_queue(...,{
+    timeout_in_seconds=1
+})
+```
+
+### Custom Client
+
+You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
+and transports.
+```python
+import httpx
+from traceotter.client import FernTraceotter
+
+client = FernTraceotter(
+    ...,
+    http_client=httpx.Client(
+        proxies="http://my.test.proxy.example.com",
+        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+    ),
+)
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

traceotter-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI (install via `pip install traceotter`)
+name = "traceotter"
+version = "0.1.0"
+description = "Agent observability Python SDK for Traceotter"
+readme = "traceotter/api/README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+  { name = "Nikhil Garakapati" }
+]
+keywords = ["traceotter", "observability", "agents", "llm", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "httpx>=0.24,<1.0",
+  "pydantic>=1.10,<3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/29m10/traceotter-python-sdk"
+Repository = "https://github.com/29m10/traceotter-python-sdk"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["traceotter*"]
+
+[tool.setuptools.package-data]
+"traceotter" = ["py.typed"]
+

traceotter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

traceotter-0.1.0/traceotter/__init__.py

@@ -0,0 +1,44 @@
+""".. include:: ../README.md"""
+
+from traceotter.experiment import Evaluation
+
+from ._client import client as _client_module
+from ._client.attributes import TraceotterOtelSpanAttributes
+from ._client.constants import ObservationTypeLiteral
+from ._client.get_client import get_client
+from ._client.observe import observe
+from ._client.span import (
+    TraceotterAgent,
+    TraceotterChain,
+    TraceotterEmbedding,
+    TraceotterEvaluator,
+    TraceotterEvent,
+    TraceotterGeneration,
+    TraceotterGuardrail,
+    TraceotterRetriever,
+    TraceotterSpan,
+    TraceotterTool,
+)
+
+Traceotter = _client_module.Traceotter
+
+__all__ = [
+    "Traceotter",
+    "get_client",
+    "observe",
+    "ObservationTypeLiteral",
+    "TraceotterSpan",
+    "TraceotterGeneration",
+    "TraceotterEvent",
+    "TraceotterOtelSpanAttributes",
+    "TraceotterAgent",
+    "TraceotterTool",
+    "TraceotterChain",
+    "TraceotterEmbedding",
+    "TraceotterEvaluator",
+    "TraceotterRetriever",
+    "TraceotterGuardrail",
+    "Evaluation",
+    "experiment",
+    "api",
+]

traceotter-0.1.0/traceotter/_client/attributes.py

@@ -0,0 +1,191 @@
+"""Span attribute management for Traceotter OpenTelemetry integration.
+
+This module defines constants and functions for managing OpenTelemetry span attributes
+used by Traceotter. It provides a structured approach to creating and manipulating
+attributes for different span types (trace, span, generation) while ensuring consistency.
+
+The module includes:
+- Attribute name constants organized by category
+- Functions to create attribute dictionaries for different entity types
+- Utilities for serializing and processing attribute values
+"""
+
+import json
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from traceotter._client.constants import (
+    ObservationTypeGenerationLike,
+    ObservationTypeSpanLike,
+)
+
+from traceotter._utils.serializer import EventSerializer
+from traceotter.model import PromptClient
+from traceotter.types import MapValue, SpanLevel
+
+
+class TraceotterOtelSpanAttributes:
+    # Traceotter-Trace attributes
+    TRACE_NAME = "traceotter.trace.name"
+    TRACE_USER_ID = "user.id"
+    TRACE_SESSION_ID = "session.id"
+    TRACE_TAGS = "traceotter.trace.tags"
+    TRACE_PUBLIC = "traceotter.trace.public"
+    TRACE_METADATA = "traceotter.trace.metadata"
+    TRACE_INPUT = "traceotter.trace.input"
+    TRACE_OUTPUT = "traceotter.trace.output"
+
+    # Traceotter-observation attributes
+    OBSERVATION_TYPE = "traceotter.observation.type"
+    OBSERVATION_METADATA = "traceotter.observation.metadata"
+    OBSERVATION_LEVEL = "traceotter.observation.level"
+    OBSERVATION_STATUS_MESSAGE = "traceotter.observation.status_message"
+    OBSERVATION_INPUT = "traceotter.observation.input"
+    OBSERVATION_OUTPUT = "traceotter.observation.output"
+
+    # Traceotter-observation of type Generation attributes
+    OBSERVATION_COMPLETION_START_TIME = "traceotter.observation.completion_start_time"
+    OBSERVATION_MODEL = "traceotter.observation.model.name"
+    OBSERVATION_MODEL_PARAMETERS = "traceotter.observation.model.parameters"
+    OBSERVATION_USAGE_DETAILS = "traceotter.observation.usage_details"
+    OBSERVATION_COST_DETAILS = "traceotter.observation.cost_details"
+    OBSERVATION_PROMPT_NAME = "traceotter.observation.prompt.name"
+    OBSERVATION_PROMPT_VERSION = "traceotter.observation.prompt.version"
+
+    # General
+    ENVIRONMENT = "traceotter.environment"
+    RELEASE = "traceotter.release"
+    VERSION = "traceotter.version"
+
+    # Internal
+    AS_ROOT = "traceotter.internal.as_root"
+
+
+def create_trace_attributes(
+    *,
+    name: Optional[str] = None,
+    user_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    version: Optional[str] = None,
+    release: Optional[str] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    metadata: Optional[Any] = None,
+    tags: Optional[List[str]] = None,
+    public: Optional[bool] = None,
+) -> dict:
+    attributes = {
+        TraceotterOtelSpanAttributes.TRACE_NAME: name,
+        TraceotterOtelSpanAttributes.TRACE_USER_ID: user_id,
+        TraceotterOtelSpanAttributes.TRACE_SESSION_ID: session_id,
+        TraceotterOtelSpanAttributes.VERSION: version,
+        TraceotterOtelSpanAttributes.RELEASE: release,
+        TraceotterOtelSpanAttributes.TRACE_INPUT: _serialize(input),
+        TraceotterOtelSpanAttributes.TRACE_OUTPUT: _serialize(output),
+        TraceotterOtelSpanAttributes.TRACE_TAGS: tags,
+        TraceotterOtelSpanAttributes.TRACE_PUBLIC: public,
+        **_flatten_and_serialize_metadata(metadata, "trace"),
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def create_span_attributes(
+    *,
+    metadata: Optional[Any] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    level: Optional[SpanLevel] = None,
+    status_message: Optional[str] = None,
+    version: Optional[str] = None,
+    observation_type: Optional[
+        Union[ObservationTypeSpanLike, Literal["event"]]
+    ] = "span",
+) -> dict:
+    attributes = {
+        TraceotterOtelSpanAttributes.OBSERVATION_TYPE: observation_type,
+        TraceotterOtelSpanAttributes.OBSERVATION_LEVEL: level,
+        TraceotterOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE: status_message,
+        TraceotterOtelSpanAttributes.VERSION: version,
+        TraceotterOtelSpanAttributes.OBSERVATION_INPUT: _serialize(input),
+        TraceotterOtelSpanAttributes.OBSERVATION_OUTPUT: _serialize(output),
+        **_flatten_and_serialize_metadata(metadata, "observation"),
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def create_generation_attributes(
+    *,
+    name: Optional[str] = None,
+    completion_start_time: Optional[datetime] = None,
+    metadata: Optional[Any] = None,
+    level: Optional[SpanLevel] = None,
+    status_message: Optional[str] = None,
+    version: Optional[str] = None,
+    model: Optional[str] = None,
+    model_parameters: Optional[Dict[str, MapValue]] = None,
+    input: Optional[Any] = None,
+    output: Optional[Any] = None,
+    usage_details: Optional[Dict[str, int]] = None,
+    cost_details: Optional[Dict[str, float]] = None,
+    prompt: Optional[PromptClient] = None,
+    observation_type: Optional[ObservationTypeGenerationLike] = "generation",
+) -> dict:
+    attributes = {
+        TraceotterOtelSpanAttributes.OBSERVATION_TYPE: observation_type,
+        TraceotterOtelSpanAttributes.OBSERVATION_LEVEL: level,
+        TraceotterOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE: status_message,
+        TraceotterOtelSpanAttributes.VERSION: version,
+        TraceotterOtelSpanAttributes.OBSERVATION_INPUT: _serialize(input),
+        TraceotterOtelSpanAttributes.OBSERVATION_OUTPUT: _serialize(output),
+        TraceotterOtelSpanAttributes.OBSERVATION_MODEL: model,
+        TraceotterOtelSpanAttributes.OBSERVATION_PROMPT_NAME: prompt.name
+        if prompt and not prompt.is_fallback
+        else None,
+        TraceotterOtelSpanAttributes.OBSERVATION_PROMPT_VERSION: prompt.version
+        if prompt and not prompt.is_fallback
+        else None,
+        TraceotterOtelSpanAttributes.OBSERVATION_USAGE_DETAILS: _serialize(usage_details),
+        TraceotterOtelSpanAttributes.OBSERVATION_COST_DETAILS: _serialize(cost_details),
+        TraceotterOtelSpanAttributes.OBSERVATION_COMPLETION_START_TIME: _serialize(
+            completion_start_time
+        ),
+        TraceotterOtelSpanAttributes.OBSERVATION_MODEL_PARAMETERS: _serialize(
+            model_parameters
+        ),
+        **_flatten_and_serialize_metadata(metadata, "observation"),
+    }
+
+    return {k: v for k, v in attributes.items() if v is not None}
+
+
+def _serialize(obj: Any) -> Optional[str]:
+    if obj is None or isinstance(obj, str):
+        return obj
+
+    return json.dumps(obj, cls=EventSerializer)
+
+
+def _flatten_and_serialize_metadata(
+    metadata: Any, type: Literal["observation", "trace"]
+) -> dict:
+    prefix = (
+        TraceotterOtelSpanAttributes.OBSERVATION_METADATA
+        if type == "observation"
+        else TraceotterOtelSpanAttributes.TRACE_METADATA
+    )
+
+    metadata_attributes: Dict[str, Union[str, int, None]] = {}
+
+    if not isinstance(metadata, dict):
+        metadata_attributes[prefix] = _serialize(metadata)
+    else:
+        for key, value in metadata.items():
+            metadata_attributes[f"{prefix}.{key}"] = (
+                value
+                if isinstance(value, str) or isinstance(value, int)
+                else _serialize(value)
+            )
+
+    return metadata_attributes