Hair Editor Agent
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:
python -m pip install -e .[dev]
Install from PyPI (when published):
pip install hair-editor-agent
Install directly from this repository:
pip install git+https://github.com/msalsas/hair-editor-agent.git
Quick start
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:
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)
- Bump the version in
pyproject.toml(e.g. to0.2.0). - Build distributions:
python -m build
- Upload to TestPyPI (create a TestPyPI API token first):
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.
Metadata
Release files for hair-editor-agent 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hair_editor_agent-0.2.0.tar.gz | 10.6 kB | Without provenance | Details for hair_editor_agent-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hair_editor_agent-0.2.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details for hair_editor_agent-0.2.0-py2.py3-none-any.whl |
Total release size: 19.5 kB
Release files / hair_editor_agent-0.2.0.tar.gz
| Download URL | hair_editor_agent-0.2.0.tar.gz |
|---|---|
| Size | 10.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
04c2f8d24ab1fd732e79b357898b07710314eda74328d7b5907dbf60a93b2232
|
|
BLAKE2b-256 checksum How to use checksums |
d7d05d323fdcf7f793cdb93cf08ec734952bd07eafd6a9bc3c6048e82da2ee3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / hair_editor_agent-0.2.0-py2.py3-none-any.whl
| Download URL | hair_editor_agent-0.2.0-py2.py3-none-any.whl |
|---|---|
| Size | 8.9 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
a5f27a443b64643bc00e4b7fbf38fce371902c79c9aea094d2171a9c571219fe
|
|
BLAKE2b-256 checksum How to use checksums |
ce2d784b5db6bbc69e701ba62720426541e722493a5e414e0eea08e1d678d837
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for hair-editor-agent 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.