Metadata-Version: 2.4
Name: artissist-logger
Version: 0.1.0
Summary: Platform-agnostic logging client for Artissist
Home-page: https://github.com/artissist/logger
Author: Artissist
Author-email: dev@artissist.com
Project-URL: Bug Reports, https://github.com/artissist/logger/issues
Project-URL: Source, https://github.com/artissist/logger
Project-URL: Documentation, https://github.com/artissist/logger
Keywords: logging,observability,telemetry,platform,artissist
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typing_extensions>=4.0.0
Requires-Dist: dataclasses; python_version < "3.7"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: pylint>=2.15.0; extra == "dev"
Requires-Dist: types-aiofiles>=22.0.0; extra == "dev"
Requires-Dist: aiofiles>=22.0.0; extra == "dev"
Provides-Extra: file
Requires-Dist: aiofiles>=22.0.0; extra == "file"
Provides-Extra: cloud
Requires-Dist: boto3>=1.26.0; extra == "cloud"
Requires-Dist: azure-monitor-opentelemetry-exporter>=1.0.0b17; extra == "cloud"
Requires-Dist: google-cloud-logging>=3.4.0; extra == "cloud"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Artissist Logger - Python Client

Platform-agnostic logging client for the Artissist platform.

## Features

- 🎯 **Pre-defined Events**: 25 built-in event types with emoji support
- 🎨 **Emoji Integration**: Configurable emoji prefixes for visual log scanning
- 📊 **Structured Logging**: Rich metadata, metrics, and error information
- 🔄 **Context Management**: Distributed tracing with correlation IDs
- 🔌 **Adapter Pattern**: Multiple output destinations (console, file, cloud)
- 🏭 **Factory Pattern**: Specialized loggers for different components
- ⚡ **Async Support**: Non-blocking logging with async/await
- 🛡️ **Type Safety**: Full type hints and runtime validation

## Installation

```bash
pip install artissist-logger
```

### Development Installation

```bash
pip install -e .[dev]
```

## Quick Start

```python
from artissist_logger import LoggerFactory, LogEvent

# Create a backend logger
logger = LoggerFactory.create_backend_logger(
    service="my-service",
    environment="development", 
    emojis=True  # Enable emojis for development
)

# Basic logging
await logger.info("Service starting up", event=LogEvent.SYSTEM_START)
await logger.error("Database connection failed", event=LogEvent.ERROR_OCCURRED)

# With structured data
await logger.info(
    "User authenticated successfully",
    event=LogEvent.USER_AUTH,
    metadata={"user_id": "user_123", "method": "oauth"},
    metrics={"auth_duration_ms": 150}
)
```

The Logger exposes convenience methods for each level (`debug`, `info`, `warn`, `error`, etc.). Use `logger.log(level, message, **kwargs)` only when the level must be chosen dynamically.

## Logger Types

### Backend Logger
```python
logger = LoggerFactory.create_backend_logger(
    service="api-server",
    environment="production",
    emojis=False  # Disabled for production
)
```

### Agent Logger  
```python
logger = LoggerFactory.create_agent_logger(
    agent_id="conv_001",
    agent_type="conversation",
    environment="development",
    emojis=True
)
```

### Infrastructure Logger
```python
logger = LoggerFactory.create_infrastructure_logger(
    component="deployment-manager", 
    environment="production"
)
```

## Context Management

### Global Context
```python
from artissist_logger import ContextManager, LoggerContext

# Set global context
ContextManager.set_context(LoggerContext(
    correlation_id="req_123",
    user_id="user_456"
))

# All subsequent logs will include this context
await logger.info("Processing request")  # Includes correlation_id and user_id
```

### Scoped Context
```python
# Temporary context for a specific operation
with ContextManager.context(user_id="user_789", operation="data_export"):
    await logger.info("Starting export")  # Includes user_id and operation
    await logger.info("Export completed")
```

### Logger Context
```python
# Create logger with permanent context
contextual_logger = logger.with_context(
    service_version="1.2.0",
    deployment_id="deploy_abc"
)

await contextual_logger.info("Service initialized")  # Includes service_version and deployment_id
```

## Events and Emojis

### Pre-defined Events
```python
# System events
LogEvent.SYSTEM_START      # 🚀 System startup
LogEvent.ERROR_OCCURRED    # 🐛 Errors and exceptions
LogEvent.WARNING_ISSUED    # ⚠️  Warning conditions

# Business events  
LogEvent.USER_AUTH         # 👤 User authentication
LogEvent.PROJECT_LIFECYCLE # 📁 Project management
LogEvent.AI_INFERENCE      # 🧠 AI model operations

# Technical events
LogEvent.API_REQUEST       # 🔄 API calls
LogEvent.DATABASE_OPERATION # 💾 Database queries
LogEvent.PERFORMANCE_METRIC # ⚡ Performance measurements
```

### Custom Events
```python
from artissist_logger import EmojiResolver, EmojiMapping

# Create custom emoji mappings
resolver = EmojiResolver()
resolver.add_custom_mapping("payment_processed", EmojiMapping(
    emoji="💳", 
    description="Payment processing events"
))

logger = LoggerFactory.create_logger(
    service="payment-service",
    environment="development", 
    adapters=["console"],
    emojis=True,
    emoji_resolver=resolver
)

# Use custom event
await logger.info("Payment completed", custom_event="payment_processed")
# Output: 💳 Payment completed
```

## Error Handling

```python
from artissist_logger import ErrorInfo

try:
    # Some operation that might fail
    process_data()
except Exception as e:
    await logger.error(
        "Data processing failed",
        event=LogEvent.ERROR_OCCURRED,
        error=ErrorInfo(
            type=type(e).__name__,
            message=str(e),
            stack_trace=traceback.format_exc(),
            context={"batch_id": "batch_123"}
        )
    )
```

## Metrics

```python
from artissist_logger import LogMetrics

# Performance metrics
await logger.info(
    "Database query completed",
    event=LogEvent.DATABASE_OPERATION,
    metrics=LogMetrics(
        duration_ms=45.2,
        count=150,
        bytes_processed=1024000
    )
)

# Business metrics
await logger.info(
    "User signup completed", 
    event=LogEvent.BUSINESS_METRIC,
    metadata={"user_type": "premium"},
    metrics=LogMetrics(
        count=1,
        custom_metrics={"revenue_impact": 29.99}
    )
)
```

## Adapters

### Console Adapter
```python
# Development console output with colors
LoggerFactory.create_logger(
    service="my-service",
    environment="development",
    adapters=["console"],
    adapter_configs={
        "console": {"colors": True, "use_stderr": False}
    }
)
```

### File Adapter
```python
# Production file logging with rotation
LoggerFactory.create_logger(
    service="my-service", 
    environment="production",
    adapters=["file"],
    adapter_configs={
        "file": {
            "file_path": "logs/service.log",
            "format": "json",
            "rotate": True,
            "max_size_mb": 50,
            "max_files": 10
        }
    }
)
```

### Multiple Adapters
```python
# Both console and file output
LoggerFactory.create_backend_logger(
    service="api-service",
    environment="production",
    adapters=["console", "file"]
)
```

## Synchronous Usage

For non-async contexts:

```python
# Synchronous convenience methods (fire-and-forget)
logger.info_sync("Service started", event=LogEvent.SYSTEM_START)
logger.error_sync("Connection failed", event=LogEvent.ERROR_OCCURRED)
```

## Configuration

### Environment Variables
```bash
export ARTISSIST_LOG_LEVEL=INFO
export ARTISSIST_LOG_EMOJIS=true
export ARTISSIST_LOG_FORMAT=json
```

### Programmatic Configuration
```python
config = {
    "service": "my-service",
    "environment": "production",
    "adapters": ["console", "file"],
    "emojis": False,
    "adapter_configs": {
        "console": {"colors": False},
        "file": {"file_path": "/var/log/my-service.log"}
    }
}

logger = LoggerFactory.create_logger(**config)
```

## Development

### Running Tests
```bash
pytest
pytest --cov=artissist_logger  # With coverage
```

### Code Formatting
```bash
black artissist_logger/
mypy artissist_logger/
flake8 artissist_logger/
```

### Build Package
```bash
python setup.py bdist_wheel
```

## Integration Examples

See the `examples/` directory for complete integration examples:
- FastAPI backend service
- Agent processing systems  
- Infrastructure deployment logging
- Error handling patterns
- Performance monitoring

## License

MIT License - see LICENSE file for details.
