avenix 0.1.0__tar.gz

avenix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentForge Contributors
+
+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.

avenix-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: avenix
+Version: 0.1.0
+Summary: Avenix is a focused Python tracing library for AI requests with beautiful terminal output
+Author: Avenix Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/avenix/avenix
+Project-URL: Repository, https://github.com/avenix/avenix
+Project-URL: Documentation, https://github.com/avenix/avenix#readme
+Keywords: ai,tracing,llm,monitoring,openai,anthropic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: rich<14.0,>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: hypothesis<7.0,>=6.0; extra == "dev"
+Requires-Dist: pytest-cov<5.0,>=4.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0,>=3.0; extra == "dev"
+Dynamic: license-file
+
+# Avenix v0.1
+
+A Python tracing library for AI/LLM requests with beautiful terminal output.
+
+Avenix provides a decorator-based API for tracing AI model requests, automatically capturing execution metrics like timing, token usage, and costs, then displaying them in richly formatted terminal output.
+
+## Overview
+
+Avenix simplifies monitoring AI/LLM requests by:
+- **Automatic Capture**: Uses a simple `@trace` decorator to automatically capture request metrics
+- **Beautiful Display**: Renders trace information in a formatted terminal panel with colors and separators
+- **Multi-Provider Support**: Works with OpenAI and Anthropic model responses out of the box
+- **Cost Tracking**: Automatically calculates request costs based on model pricing
+- **Extensible**: Easy to add custom extractors for new AI providers
+
+## Installation
+
+```bash
+pip install avenix
+```
+
+## Requirements
+
+- Python 3.11+
+- pydantic ^2.0
+- rich ^13.0
+
+## Quick Start
+
+### Using the @trace Decorator
+
+The simplest way to use Avenix is with the `@trace` decorator:
+
+```python
+from avenix import trace
+from openai import OpenAI
+
+client = OpenAI()
+
+@trace
+def get_gpt_response(prompt: str):
+    """Call GPT-4 with the given prompt."""
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response
+
+# When you call the function, Avenix will automatically:
+# 1. Measure execution time
+# 2. Extract model, tokens, and response from the result
+# 3. Calculate cost based on token usage
+# 4. Display formatted trace output to terminal
+result = get_gpt_response("What is machine learning?")
+```
+
+### Manual Trace Creation
+
+For more control, you can manually create traces using the `Tracer` API:
+
+```python
+from avenix import Tracer
+
+tracer = Tracer()
+
+# Later, manually create a trace with explicit values
+tracer.create_trace(
+    model="gpt-4",
+    latency=2.5,
+    input_tokens=150,
+    output_tokens=300,
+    cost=0.045,
+    prompt="What is AI?",
+    response="AI is artificial intelligence..."
+)
+```
+
+## Supported Models
+
+Avenix includes built-in support for:
+
+### OpenAI
+- gpt-4
+- gpt-4-turbo
+- gpt-3.5-turbo
+
+### Anthropic
+- claude-3-opus
+- claude-3-sonnet
+- claude-3-haiku
+
+## Features in v0.1
+
+✅ Decorator-based tracing API
+✅ Automatic timing measurement with perf_counter
+✅ OpenAI and Anthropic response extraction
+✅ Model pricing table and cost calculation
+✅ Beautiful terminal output with rich formatting
+✅ Error handling and graceful fallbacks
+✅ Property-based test suite for correctness verification
+
+## Out of Scope for v0.1
+
+The following features are planned for future releases:
+
+- Custom formatter plugins
+- Database/file persistence of traces
+- Trace filtering and search
+- Performance statistics aggregation
+- Integration with external logging services
+- Support for additional AI providers
+- Rate limiting and quota management
+- Async/await support
+
+## Documentation
+
+### API Reference
+
+#### @trace Decorator
+
+```python
+@trace
+def your_function():
+    # ... your code that calls an AI model
+    return response
+```
+
+The `@trace` decorator:
+- Measures execution time with `time.perf_counter()`
+- Captures the function result
+- Calls the global `Tracer` instance to extract data and display trace
+- Propagates exceptions without suppression
+- Preserves the original function's return value and metadata
+
+#### Tracer Class
+
+```python
+from avenix import Tracer
+
+tracer = Tracer(logger=None, formatter=None)
+```
+
+Methods:
+- `capture_trace(result, latency, func_name=None)`: Capture and display a trace from function execution
+- `create_trace(model, latency, input_tokens, output_tokens, cost, prompt, response)`: Manually create and display a trace
+
+### TraceModel
+
+The `TraceModel` class represents a single trace with validation:
+
+Fields:
+- `model` (str): Name of the AI model
+- `latency` (float): Execution time in seconds (rounded to 2 decimals)
+- `input_tokens` (int): Number of input tokens (must be non-negative)
+- `output_tokens` (int): Number of output tokens (must be non-negative)
+- `cost` (float): Request cost in dollars (rounded to 4 decimals, must be non-negative)
+- `prompt` (str): Input prompt text (defaults to empty string)
+- `response` (str): Model response text (defaults to empty string)
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `openai_example.py`: Using @trace with OpenAI API
+- `anthropic_example.py`: Using @trace with Anthropic API
+- `manual_trace.py`: Creating traces manually with Tracer API
+
+## Testing
+
+Avenix includes a comprehensive test suite with property-based tests:
+
+```bash
+pytest tests/ -v                    # Run all tests
+pytest tests/ --cov                 # Run with coverage report
+pytest tests/test_models.py -v      # Run specific test file
+```
+
+Test coverage targets:
+- Core modules (decorator, tracer, models, formatter, extractors): >90%
+- Property-based tests for 16 correctness properties
+- Unit tests for all feature components
+
+## Architecture
+
+Avenix follows a layered architecture:
+
+1. **Models Layer** (`models.py`): Defines `TraceModel` with Pydantic validation
+2. **Decorator Layer** (`decorator.py`): Provides `@trace` decorator for wrapping functions
+3. **Tracer Layer** (`tracer.py`): Core orchestration with optional custom logger/formatter
+4. **Extraction Layer** (`extractors.py`): Provider-specific response extractors
+5. **Formatting Layer** (`formatter.py`): Beautiful terminal output with rich library
+6. **Logging Layer** (`logger.py`): Terminal display with fallback handling
+
+## Error Handling
+
+Avenix is designed to be resilient to errors:
+
+- **Extraction Failures**: If response format doesn't match known providers, uses sensible defaults
+- **Validation Failures**: If TraceModel validation fails, falls back to defaults
+- **Rendering Failures**: If rich formatting fails, falls back to basic print output
+- **Exception Propagation**: Errors in traced functions propagate normally without suppression
+
+## Contributing
+
+This is a v0.1 release. Feedback and contributions are welcome!
+
+## API Reference
+
+For detailed API documentation, see [API.md](API.md).
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Changelog
+
+See CHANGELOG.md for version history and release notes

avenix-0.1.0/README.md

@@ -0,0 +1,217 @@
+# Avenix v0.1
+
+A Python tracing library for AI/LLM requests with beautiful terminal output.
+
+Avenix provides a decorator-based API for tracing AI model requests, automatically capturing execution metrics like timing, token usage, and costs, then displaying them in richly formatted terminal output.
+
+## Overview
+
+Avenix simplifies monitoring AI/LLM requests by:
+- **Automatic Capture**: Uses a simple `@trace` decorator to automatically capture request metrics
+- **Beautiful Display**: Renders trace information in a formatted terminal panel with colors and separators
+- **Multi-Provider Support**: Works with OpenAI and Anthropic model responses out of the box
+- **Cost Tracking**: Automatically calculates request costs based on model pricing
+- **Extensible**: Easy to add custom extractors for new AI providers
+
+## Installation
+
+```bash
+pip install avenix
+```
+
+## Requirements
+
+- Python 3.11+
+- pydantic ^2.0
+- rich ^13.0
+
+## Quick Start
+
+### Using the @trace Decorator
+
+The simplest way to use Avenix is with the `@trace` decorator:
+
+```python
+from avenix import trace
+from openai import OpenAI
+
+client = OpenAI()
+
+@trace
+def get_gpt_response(prompt: str):
+    """Call GPT-4 with the given prompt."""
+    response = client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response
+
+# When you call the function, Avenix will automatically:
+# 1. Measure execution time
+# 2. Extract model, tokens, and response from the result
+# 3. Calculate cost based on token usage
+# 4. Display formatted trace output to terminal
+result = get_gpt_response("What is machine learning?")
+```
+
+### Manual Trace Creation
+
+For more control, you can manually create traces using the `Tracer` API:
+
+```python
+from avenix import Tracer
+
+tracer = Tracer()
+
+# Later, manually create a trace with explicit values
+tracer.create_trace(
+    model="gpt-4",
+    latency=2.5,
+    input_tokens=150,
+    output_tokens=300,
+    cost=0.045,
+    prompt="What is AI?",
+    response="AI is artificial intelligence..."
+)
+```
+
+## Supported Models
+
+Avenix includes built-in support for:
+
+### OpenAI
+- gpt-4
+- gpt-4-turbo
+- gpt-3.5-turbo
+
+### Anthropic
+- claude-3-opus
+- claude-3-sonnet
+- claude-3-haiku
+
+## Features in v0.1
+
+✅ Decorator-based tracing API
+✅ Automatic timing measurement with perf_counter
+✅ OpenAI and Anthropic response extraction
+✅ Model pricing table and cost calculation
+✅ Beautiful terminal output with rich formatting
+✅ Error handling and graceful fallbacks
+✅ Property-based test suite for correctness verification
+
+## Out of Scope for v0.1
+
+The following features are planned for future releases:
+
+- Custom formatter plugins
+- Database/file persistence of traces
+- Trace filtering and search
+- Performance statistics aggregation
+- Integration with external logging services
+- Support for additional AI providers
+- Rate limiting and quota management
+- Async/await support
+
+## Documentation
+
+### API Reference
+
+#### @trace Decorator
+
+```python
+@trace
+def your_function():
+    # ... your code that calls an AI model
+    return response
+```
+
+The `@trace` decorator:
+- Measures execution time with `time.perf_counter()`
+- Captures the function result
+- Calls the global `Tracer` instance to extract data and display trace
+- Propagates exceptions without suppression
+- Preserves the original function's return value and metadata
+
+#### Tracer Class
+
+```python
+from avenix import Tracer
+
+tracer = Tracer(logger=None, formatter=None)
+```
+
+Methods:
+- `capture_trace(result, latency, func_name=None)`: Capture and display a trace from function execution
+- `create_trace(model, latency, input_tokens, output_tokens, cost, prompt, response)`: Manually create and display a trace
+
+### TraceModel
+
+The `TraceModel` class represents a single trace with validation:
+
+Fields:
+- `model` (str): Name of the AI model
+- `latency` (float): Execution time in seconds (rounded to 2 decimals)
+- `input_tokens` (int): Number of input tokens (must be non-negative)
+- `output_tokens` (int): Number of output tokens (must be non-negative)
+- `cost` (float): Request cost in dollars (rounded to 4 decimals, must be non-negative)
+- `prompt` (str): Input prompt text (defaults to empty string)
+- `response` (str): Model response text (defaults to empty string)
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `openai_example.py`: Using @trace with OpenAI API
+- `anthropic_example.py`: Using @trace with Anthropic API
+- `manual_trace.py`: Creating traces manually with Tracer API
+
+## Testing
+
+Avenix includes a comprehensive test suite with property-based tests:
+
+```bash
+pytest tests/ -v                    # Run all tests
+pytest tests/ --cov                 # Run with coverage report
+pytest tests/test_models.py -v      # Run specific test file
+```
+
+Test coverage targets:
+- Core modules (decorator, tracer, models, formatter, extractors): >90%
+- Property-based tests for 16 correctness properties
+- Unit tests for all feature components
+
+## Architecture
+
+Avenix follows a layered architecture:
+
+1. **Models Layer** (`models.py`): Defines `TraceModel` with Pydantic validation
+2. **Decorator Layer** (`decorator.py`): Provides `@trace` decorator for wrapping functions
+3. **Tracer Layer** (`tracer.py`): Core orchestration with optional custom logger/formatter
+4. **Extraction Layer** (`extractors.py`): Provider-specific response extractors
+5. **Formatting Layer** (`formatter.py`): Beautiful terminal output with rich library
+6. **Logging Layer** (`logger.py`): Terminal display with fallback handling
+
+## Error Handling
+
+Avenix is designed to be resilient to errors:
+
+- **Extraction Failures**: If response format doesn't match known providers, uses sensible defaults
+- **Validation Failures**: If TraceModel validation fails, falls back to defaults
+- **Rendering Failures**: If rich formatting fails, falls back to basic print output
+- **Exception Propagation**: Errors in traced functions propagate normally without suppression
+
+## Contributing
+
+This is a v0.1 release. Feedback and contributions are welcome!
+
+## API Reference
+
+For detailed API documentation, see [API.md](API.md).
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Changelog
+
+See CHANGELOG.md for version history and release notes

avenix-0.1.0/avenix/__init__.py

@@ -0,0 +1,11 @@
+"""
+Avenix - Python tracing library for AI requests.
+
+Provides decorator-based tracing for AI/LLM requests with beautiful terminal output.
+"""
+
+from .decorator import trace
+from .tracer import Tracer
+
+__version__ = "0.1.0"
+__all__ = ["trace", "Tracer"]

avenix-0.1.0/avenix/decorator.py

@@ -0,0 +1,62 @@
+# Trace decorator implementation
+
+import functools
+import time
+from typing import Callable, Any
+
+
+def trace(func: Callable) -> Callable:
+    """
+    Decorator that traces AI request function execution.
+    
+    Captures timing, model info, tokens, cost, prompt, and response.
+    Displays formatted trace to terminal after execution.
+    
+    Args:
+        func: The function to trace (should return AI response object)
+    
+    Returns:
+        Wrapped function with identical signature and return type
+        
+    Example:
+        @trace
+        def call_openai(prompt: str):
+            return client.chat.completions.create(
+                model="gpt-4",
+                messages=[{"role": "user", "content": prompt}]
+            )
+    """
+    from .tracer import Tracer
+    
+    # Create tracer instance once at decoration time
+    tracer = Tracer()
+    
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Record start time with high precision
+        start_time = time.perf_counter()
+        
+        try:
+            # Execute the wrapped function
+            result = func(*args, **kwargs)
+            
+            # Calculate latency
+            end_time = time.perf_counter()
+            latency = end_time - start_time
+            
+            # Capture and display trace
+            tracer.capture_trace(
+                result=result,
+                latency=latency,
+                func_name=func.__name__
+            )
+            
+            # Return original result unchanged
+            return result
+            
+        except Exception:
+            # Propagate exceptions without suppression
+            # No trace is captured on failure
+            raise
+    
+    return wrapper

avenix-0.1.0/avenix/extractors.py

@@ -0,0 +1,81 @@
+# Provider-specific extraction logic for AI responses
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseExtractor(ABC):
+    """Abstract base class for AI response extractors."""
+    
+    @abstractmethod
+    def can_extract(self, result: Any) -> bool:
+        """Check if this extractor can handle the given result."""
+        ...
+    
+    @abstractmethod
+    def extract(self, result: Any) -> Dict[str, Any]:
+        """Extract trace data from result."""
+        ...
+
+
+class OpenAIExtractor(ResponseExtractor):
+    """Extractor for OpenAI response format."""
+    
+    def can_extract(self, result: Any) -> bool:
+        """Check if result matches OpenAI format."""
+        usage = getattr(result, 'usage', None)
+        choices = getattr(result, 'choices', None)
+
+        return (
+            hasattr(result, 'model') and
+            hasattr(usage, 'prompt_tokens') and
+            hasattr(usage, 'completion_tokens') and
+            isinstance(choices, (list, tuple))
+        )
+    
+    def extract(self, result: Any) -> Dict[str, Any]:
+        """Extract trace data from OpenAI response."""
+        try:
+            return {
+                'model': result.model,
+                'input_tokens': result.usage.prompt_tokens,
+                'output_tokens': result.usage.completion_tokens,
+                'prompt': '',  # Not available in response
+                'response': result.choices[0].message.content
+            }
+        except (AttributeError, IndexError) as e:
+            logger.warning(f"Failed to extract OpenAI trace data: {e}")
+            return {}
+
+
+class AnthropicExtractor(ResponseExtractor):
+    """Extractor for Anthropic response format."""
+    
+    def can_extract(self, result: Any) -> bool:
+        """Check if result matches Anthropic format."""
+        usage = getattr(result, 'usage', None)
+        content = getattr(result, 'content', None)
+
+        return (
+            hasattr(result, 'model') and
+            hasattr(usage, 'input_tokens') and
+            hasattr(usage, 'output_tokens') and
+            isinstance(content, (list, tuple))
+        )
+    
+    def extract(self, result: Any) -> Dict[str, Any]:
+        """Extract trace data from Anthropic response."""
+        try:
+            return {
+                'model': result.model,
+                'input_tokens': result.usage.input_tokens,
+                'output_tokens': result.usage.output_tokens,
+                'prompt': '',  # Not available in response
+                'response': result.content[0].text if result.content else ''
+            }
+        except (AttributeError, IndexError) as e:
+            logger.warning(f"Failed to extract Anthropic trace data: {e}")
+            return {}