Metadata-Version: 2.4
Name: untrace-sdk
Version: 0.1.0
Summary: LLM observability SDK for Python
Project-URL: Homepage, https://github.com/untrace-dev/untrace-sdk
Project-URL: Repository, https://github.com/untrace-dev/untrace-sdk
Project-URL: Documentation, https://docs.untrace.dev
Project-URL: Bug Tracker, https://github.com/untrace-dev/untrace-sdk/issues
Author-email: Untrace <hello@untrace.dev>
License: MIT
Keywords: llm,monitoring,observability,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Untrace SDK for Python

LLM observability SDK for Python applications.

## Installation

```bash
pip install untrace-sdk
```

## Quick Start

```python
import asyncio
from untrace import UntraceClient

async def main():
    # Initialize the client
    async with UntraceClient(api_key="your-api-key") as client:
        # Send a trace event
        trace = await client.trace(
            event_type="llm_call",
            data={
                "model": "gpt-4",
                "prompt": "Hello, world!",
                "response": "Hello! How can I help you today?",
                "tokens_used": 25,
            },
            metadata={
                "user_id": "user123",
                "session_id": "session456",
            }
        )

        print(f"Trace created: {trace.id}")

# Run the async function
asyncio.run(main())
```

## Synchronous Usage

```python
from untrace import UntraceClient

# Initialize the client
client = UntraceClient(api_key="your-api-key")

# Send a trace event
trace = client.trace_sync(
    event_type="llm_call",
    data={
        "model": "gpt-4",
        "prompt": "Hello, world!",
        "response": "Hello! How can I help you today?",
    }
)

print(f"Trace created: {trace.id}")

# Don't forget to close the client
client.close()
```

## API Reference

### UntraceClient

The main client class for interacting with the Untrace API.

#### Constructor

```python
UntraceClient(
    api_key: str,
    base_url: str = "https://api.untrace.dev",
    timeout: float = 30.0,
)
```

#### Methods

- `trace(event_type, data, metadata=None)`: Send a trace event (async)
- `trace_sync(event_type, data, metadata=None)`: Send a trace event (sync)
- `get_trace(trace_id)`: Retrieve a trace by ID (async)
- `close()`: Close the HTTP client

## Error Handling

The SDK provides specific exception types for different error scenarios:

- `UntraceError`: Base exception for all SDK errors
- `UntraceAPIError`: Raised when API requests fail
- `UntraceValidationError`: Raised when request validation fails

```python
from untrace import UntraceClient, UntraceAPIError, UntraceValidationError

try:
    client = UntraceClient(api_key="your-api-key")
    trace = client.trace_sync("llm_call", {"model": "gpt-4"})
except UntraceValidationError as e:
    print(f"Validation error: {e}")
except UntraceAPIError as e:
    print(f"API error: {e}")
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/untrace-dev/untrace-sdk.git
cd untrace-sdk/sdks/python

# Install in development mode
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black src/
isort src/
ruff check src/
```

## License

MIT License - see LICENSE file for details.
