Metadata-Version: 2.4
Name: sgai-evaluator
Version: 0.1.9
Summary: Universal tracing middleware for agent applications with support for multiple tracing backends
Project-URL: Homepage, https://github.com/armaansayyad/sgai-evaluator
Project-URL: Bug Tracker, https://github.com/armaansayyad/sgai-evaluator/issues
Author-email: Armaan Sayyad <armaans999@gmail.com>, Aarav Aggarwal <aarav.a0624@gmail.com>
License-File: LICENSE
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Requires-Dist: langfuse>=2.0.0
Requires-Dist: openinference-instrumentation-anthropic
Requires-Dist: openinference-instrumentation-langchain
Requires-Dist: openinference-instrumentation-llama-index
Requires-Dist: openinference-instrumentation-openai
Requires-Dist: openinference-instrumentation>=0.1.27
Description-Content-Type: text/markdown

# SGAI Evaluator

A universal tracing middleware for agent applications with support for multiple tracing backends. This package provides automatic tracing setup - just import it and it works!

## Features

- 🔄 Zero-configuration setup - just import and go!
- 🤖 Automatic framework detection and integration
  - OpenAI Agents SDK
  - Google ADK
  - CrewAI
  - LangChain
- 🎯 Manual instrumentation if needed
- 🔌 Extensible backend system
- 🚀 Async/sync support

## Installation

```bash
pip install sgai-evaluator
```

## Quick Start

The simplest way to use SGAI Evaluator is to just import it:

```python
# Just import the package - it automatically sets up tracing
import sgai_evaluator

# Your existing code will now be traced automatically!
```

If you need more control, you can use the manual instrumentation:

```python
from sgai_evaluator import trace, start_span, start_generation

# Optional: Use decorators for specific functions
@trace(name="my_function")
def my_function(arg1, arg2):
    return arg1 + arg2

# Optional: Use context managers for manual tracing
with start_span("manual_operation") as span:
    result = perform_operation()
    span.update(output=result)

# Optional: Track LLM generations specifically
with start_generation("text_generation", model="gpt-4") as span:
    response = llm.generate("Hello!")
    span.update(output=response)
```

## Configuration

The package uses environment variables for configuration:

- `SGAI_TRACER`: The tracing backend to use (default: 'langfuse')
- `SGAI_SERVICE_NAME`: Service name for framework integrations (default: 'agent_service')
- `AGENT_NAME`: Agent name for automatic tagging of all traces (optional)

For Langfuse backend:
- `LANGFUSE_PUBLIC_KEY`
- `LANGFUSE_SECRET_KEY`
- `LANGFUSE_HOST` (optional)

## API Reference

### Automatic Tracing

Just import the package and it will automatically:
- Detect and instrument supported frameworks
- Set up appropriate tracing backends
- Configure default settings

### Manual Instrumentation (Optional)

#### Decorators

`@trace(name=None, **kwargs)`
```python
@trace(name="custom_name", tags=["tag1", "tag2"])
def my_function():
    pass
```

#### Context Managers

`start_span(context, **kwargs)`
```python
with start_span("operation_name", tags=["tag1"]) as span:
    result = operation()
    span.update(output=result)
```

`start_generation(name, model, **kwargs)`
```python
with start_generation("text_gen", model="gpt-4") as span:
    response = llm.generate("prompt")
    span.update(output=response)
```

### Agent Name Configuration

`set_agent_name(name)`
```python
from sgai_evaluator import set_agent_name

# Set agent name for all traces (overrides AGENT_NAME environment variable)
set_agent_name('MyAgentName')
```

#### Environment Variable (Recommended)
```bash
# .env file
AGENT_NAME=MyProductionAgent
```

All traces will be automatically tagged with the agent name for better organization and filtering.

### Utility Functions

`flush()`
```python
from sgai_evaluator import flush

# After operations
flush()
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details. 