Metadata-Version: 2.4
Name: tracewise-ai
Version: 0.1.0
Summary: Python SDK for observability, tracing, and evaluation of LLM applications
Project-URL: Homepage, https://github.com/arash-arora/tracewise
Project-URL: Repository, https://github.com/arash-arora/tracewise
Author: Tracewise Authors
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: arize-phoenix-evals>=2.7.1
Requires-Dist: clickhouse-driver>=0.2.7
Requires-Dist: clickhouse-sqlalchemy>=0.3.0
Requires-Dist: deepeval>=3.7.7
Requires-Dist: fastapi>=0.111.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: langchain-core>=0.1.52
Requires-Dist: langchain-groq>=0.1.3
Requires-Dist: langchain-openai>=0.1.1
Requires-Dist: langgraph>=0.0.39
Requires-Dist: opentelemetry-api>=1.24.0
Requires-Dist: opentelemetry-sdk>=1.24.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: ragas>=0.4.2
Requires-Dist: sqlalchemy>=2.0.29
Provides-Extra: eval
Requires-Dist: arize-phoenix-evals; extra == 'eval'
Requires-Dist: deepeval>=0.21.0; extra == 'eval'
Requires-Dist: ragas>=0.1.0; extra == 'eval'
Description-Content-Type: text/markdown

# Tracewise

**Tracewise** is a Python SDK for **observability, tracing, and evaluation of LLM applications**, designed to be embedded directly into your codebase as a **git submodule**.

It provides:

- End-to-end tracing for LLM calls and agent workflows
- Unified evaluation across popular LLM evaluation frameworks
- Lightweight HTTP exporters
- Scalable storage with ClickHouse and Postgres
- First-class integrations with LangChain-based LLMs

---

## Why Tracewise?

- 🧩 **Submodule-first**: Version observability alongside your application code
- 🔍 **Deep tracing**: Automatic instrumentation for LLM calls and workflows
- 📊 **Evaluation-native**: Built-in support for multiple evaluation frameworks
- ⚡ **Low overhead**: Async, HTTP-based exporters
- 🧠 **LLM-aware**: Native wrappers for LangChain + Groq / OpenAI

---

## Features

### Tracing

- Automatic tracing via decorators
- LLM call metadata (model, tokens, latency)
- Workflow and agent-level traces

### Evaluation

Integrated support for:

- [**DeepEval**](https://github.com/confident-ai/deepeval)
- [**Ragas**](https://github.com/explodinggradients/ragas)
- [**Arize Phoenix**](https://github.com/Arize-ai/phoenix)
- **Tracewise Evaluation** (agent & tool-based evaluation)

### Storage

- **ClickHouse** → traces, spans, metrics
- **PostgreSQL** → users, projects, API keys

### LLM Integrations

- LangChain-compatible wrappers
- Supported providers:
  - Groq
  - OpenAI
  - Azure OpenAI

---

## Installation (Git Submodule – Recommended)

Tracewise is intended to be used **as a git submodule**, not as a standalone pip dependency.

```bash
git submodule add https://github.com/your-org/tracewise.git tracewise
```

## Quick Start

```python
from tracewise.llm.langchain import ChatGroq
from tracewise import observe, init_observability
from tracewise.llm.openai import OpenAI, AzureOpenAI

# Use the observe decorator
@observe(agent_name)
def my_llm_function(prompt: str) -> str:
    # Your LLM logic here

    # Langchain
    llm = ChatGroq(model="openai/gpt-oss/120b", temperature=0)
    response = llm.invoke("Hi")

    # OpenAI
    llm = OpenAI()
    response = llm.responses.create(
      model="gpt-4o",
      messages=[{
        "role": "assistant", "content": "You're a helpful agent",
        "role": "user", "content": "Hi"
      }]
    )

    # Azure OpenAI
    llm = AzureOpenAI(api_key="", azure_endpoint="", api_version="")
    response = llm.chat.completions.create(
      model=<deployment_name>, 
      messages=[{
        "role": "assistant", "content": "You're a helpful agent",
        "role": "user", "content": "Hi"
      }]
    )

    return response
```

## Configuration

Configure via environment variables:

```bash
export TRACEWISE_URL=http://localhost:8000
export TRACEWISE_API_KEY=your-api-key
```

Or programmatically:

```python
init_observability(url="http://localhost:8000", api_key="your-api-key")
```

## Git Submodule Usage

This repository can be used as a git submodule in your project:

```bash
git submodule add https://github.com/your-org/tracewise.git path/to/tracewise
```

Then install as an editable package:

```bash
pip install -e path/to/tracewise
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/your-org/tracewise.git
cd tracewise

# Install dependencies
pip install -e .
```

### Testing

```bash
pytest
```

### Linting

```bash
ruff check .
mypy src/
```