Metadata-Version: 2.4
Name: dermalytics
Version: 0.1.5
Summary: Python SDK for the Dermalytics API - Skincare Ingredient Analysis
Home-page: https://github.com/dermalytics-dev/dermalytics-python
Author: Dermalytics
Author-email: Dermalytics <support@dermalytics.dev>
License: MIT
Project-URL: Homepage, https://github.com/dermalytics-dev/dermalytics-python
Project-URL: Documentation, https://docs.dermalytics.dev
Project-URL: Repository, https://github.com/dermalytics-dev/dermalytics-python
Project-URL: Issues, https://github.com/dermalytics-dev/dermalytics-python/issues
Keywords: skincare,ingredients,api,dermatology,cosmetics
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Dermalytics Python SDK

Python SDK for the [Dermalytics API](https://dermalytics.dev) - Skincare Ingredient Analysis and Safety Ratings.

## ⚠️ Status

This SDK is currently in **development** and **alpha testing**. The API is functional but may have breaking changes in future versions. Use with caution in production environments.

## Installation

```bash
pip install dermalytics
```

## Quick Start

```python
from dermalytics import Dermalytics

# Initialize the client
client = Dermalytics(api_key="your_api_key_here")

# Get ingredient details
ingredient = client.get_ingredient("niacinamide")
print(ingredient)
# {
#     "name": "niacinamide",
#     "severity": "safe",
#     "description": "A form of vitamin B3",
#     "category": "Vitamins",
#     "synonyms": ["nicotinamide"],
#     "credits_remaining": 99,
# }

# Analyze a product
analysis = client.analyze_product([
    "Aqua",
    "Glycerin",
    "Niacinamide",
    "Salicylic Acid",
    "Hyaluronic Acid"
])
print(analysis)
# {
#     "safety_status": "safe",
#     "ingredients": [{"name": "Aqua", "found": True, "severity": "safe", "category": "Solvent"}],
#     "credits_remaining": 99,
# }
```

## API Reference

### `Dermalytics(api_key: str, base_url: Optional[str] = None)`

Initialize the Dermalytics API client.

**Parameters:**
- `api_key` (str): Your Dermalytics API key
- `base_url` (str, optional): Base URL for the API (defaults to `https://api.dermalytics.dev`)

**Raises:**
- `ValidationError`: If API key is missing or invalid

### `get_ingredient(name: str) -> Ingredient`

Get detailed information about a specific ingredient.

**Parameters:**
- `name` (str): The name of the ingredient to look up (e.g., "niacinamide")

**Returns:**
- `Ingredient`: Dictionary containing:
  - `name` (str): Ingredient name
  - `severity` (str): Safety rating (`safe`, `low_risk`, `moderate_risk`, `high_risk`)
  - `description`, `comedogenicity`, `irritancy`, `formula`, `molecular_weight`, `cas_no`, `ec_no`, `ph_eur_name`, `functions`: Detail fields (see OpenAPI `IngredientResponse`)
  - `category` (str, optional): Category label when present
  - `synonyms` (list): Alternative names for the ingredient
  - `credits_remaining` (int): Account credit balance after this request

**Raises:**
- `ValidationError`: If the ingredient name is invalid
- `NotFoundError`: If the ingredient is not found
- `AuthenticationError`: If authentication fails
- `RateLimitError`: If rate limit is exceeded
- `APIError`: For other API errors

### `analyze_product(ingredients: List[str]) -> ProductAnalysis`

Analyze a complete product formulation.

**Parameters:**
- `ingredients` (List[str]): List of ingredient names in the product

**Returns:**
- `ProductAnalysis`: Dictionary containing:
  - `safety_status` (str): Overall safety status of the formulation
  - `ingredients` (list): Rows with `name`, `found`, `severity`, `category`, and the same detail fields as single-ingredient lookup
  - `credits_remaining` (int): Account credit balance after this request

**Raises:**
- `ValidationError`: If the ingredients array is invalid
- `AuthenticationError`: If authentication fails
- `RateLimitError`: If rate limit is exceeded
- `APIError`: For other API errors

## Error Handling

The SDK provides comprehensive error handling with specific error classes for different scenarios:

```python
from dermalytics import (
    DermalyticsError,
    APIError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

try:
    ingredient = client.get_ingredient("niacinamide")
except NotFoundError:
    print("Ingredient not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ValidationError as e:
    print(f"Invalid input: {e.message}")
except APIError as e:
    print(f"API error: {e.message}")
except DermalyticsError as e:
    print(f"Dermalytics error: {e.message}")
```

### Error Classes

- `DermalyticsError` - Base error class for all SDK errors
- `APIError` - General API errors (server errors, network issues, invalid responses)
- `AuthenticationError` - Authentication failures (401, 403)
- `NotFoundError` - Resource not found (404)
- `RateLimitError` - Rate limit exceeded (429)
- `ValidationError` - Invalid request data (400, invalid input parameters)

## Development

### Setup

1. Clone the repository:
```bash
git clone https://github.com/dermalytics-dev/dermalytics-python.git
cd dermalytics-python
```

2. Install development dependencies:
```bash
pip install -r requirements.txt
```

3. Install the package in development mode:
```bash
pip install -e .
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black dermalytics tests
```

### Type Checking

```bash
mypy dermalytics
```

## Contributing

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

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

The MIT License allows you to:
- ✅ Use the code commercially
- ✅ Modify the code
- ✅ Distribute the code
- ✅ Use privately
- ✅ Include in proprietary software

You must:
- Include the original copyright notice
- Include the license text

## Links

- [Dermalytics API Documentation](https://docs.dermalytics.dev)
- [GitHub Repository](https://github.com/dermalytics-dev/dermalytics-python)
- [Issue Tracker](https://github.com/dermalytics-dev/dermalytics-python/issues)
- [PyPI Package](https://pypi.org/project/dermalytics/)

## Support

For support, email support@dermalytics.dev or open an issue on GitHub.
