hair-editor-agent 0.2.0
Specialized agent for hair style and color editing
License: MIT
Requires Python: >=3.8

# Hair Editor Agent

[![PyPI](https://img.shields.io/pypi/v/hair-editor-agent.svg)](https://pypi.org/project/hair-editor-agent/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hair-editor-agent.svg)](https://pypi.org/project/hair-editor-agent/)
[![CI](https://github.com/msalsas/hair-editor-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/msalsas/hair-editor-agent/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/msalsas/hair-editor-agent.svg)](https://github.com/msalsas/hair-editor-agent/blob/main/LICENSE)

Hair Editor Agent is an AI-powered Python library and agent for realistic hairstyle and hair-color editing using image models and vision-capable LLMs.

This package focuses on flexible, descriptive editing: orchestrators may pass free-form textual descriptions for `hair_style` and `hair_color` (for example: "Shoulder-length wavy hair with subtle balayage highlights, loose beachy waves"). The agent handles image validation, optional image size/quality tuning, and forwards requests to a configurable LLM-backed client.

## Key features

- Free-form hairstyle editing: accept detailed textual descriptions (length, texture, cut, layers, styling).
- Hair color transformations: accept descriptive color instructions (e.g. "rose gold with warm undertones").
- Change appearance task: combine style and color transformations in a single request.
- Optional client-side image resizing/compression to reduce payload size and latency.
- Simple, test-friendly API designed for integration into larger orchestrators and CI-driven publishing.

## Installation

Developer / editable install:

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

Install from PyPI (when published):

```bash
pip install hair-editor-agent
```

Install directly from this repository:

```bash
pip install git+https://github.com/msalsas/hair-editor-agent.git
```

## Quick start

```python
from hair_editor_agent import HairEditorAgent
from agent_core_framework import AgentTask

# Create the agent. You can tune image payload size via max_image_size and jpeg_quality.
agent = HairEditorAgent(openrouter_api_key="YOUR_API_KEY", max_image_size=1024, jpeg_quality=85)

# Edit hair style and color with descriptive strings
task = AgentTask(
    type="edit_hair_style",
    payload={
        "image_path": "photo.jpg",
        "hair_style": "Shoulder-length wavy hair with subtle balayage highlights, loose beachy waves",
        "hair_color": "warm chestnut with golden highlights"
    }
)
response = agent.process(task)
print(response.success, response.error)
print(response.data)  # contains edited_image_path and echoed style/color when successful
```

Supported task types (examples): `edit_hair_style`, `edit_hair_color`, `change_appearance`.

## Testing

Run the test suite locally:

```bash
python -m pytest
```

(Use `PYTHONPATH=src` if running tests from the project root to import the local package: `PYTHONPATH=src pytest -q`)

## Publishing to TestPyPI (manual)

1. Bump the version in `pyproject.toml` (e.g. to `0.2.0`).
2. Build distributions:

```bash
python -m build
```

3. Upload to TestPyPI (create a TestPyPI API token first):

```bash
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
```

## Notes on CI

A GitHub Actions workflow (`.github/workflows/publish.yml`) can be included to automate publishing. To enable automated publishing to TestPyPI, add your TestPyPI token as a repository secret named `TEST_PYPI_API_TOKEN` and run the workflow manually or by pushing a test tag.

The repository also contains tests and basic CI configuration; ensure your runner has Pillow and test dependencies available.

## Contributing

Contributions are welcome. Please open an issue or a pull request. Follow the existing code style, add tests for new behavior, and keep changes focused and small. If you add or change public behavior, add/adjust unit tests accordingly.

## License

MIT — see the `LICENSE` file for details.