Facial Vision Agent
Facial Vision Agent is an AI-powered library for analyzing facial morphology and hair characteristics from images using vision models and vision-capable LLMs.
This package focuses on visual feature extraction — it identifies facial proportions and prominent features and analyzes hair type, length, density and condition. It is designed to be used as a Python package and integrated into larger systems as an agent that processes image analysis tasks.
Key features
- Facial feature detection: face shape, proportions, forehead, eyebrows, eyes, nose, mouth, chin and jawline.
- Hair analysis: type (straight/wavy/curly/coily), length, approximate color, density and condition.
- Confidence metrics for each analysis stage.
- Lightweight API designed for automated testing and CI-driven publishing.
Installation
Developer / editable install:
python -m pip install -e .[dev]
Install from PyPI (when published):
pip install facial-vision-agent
Quick start
from facial_vision_agent import FacialVisionAgent
from agent_core_framework import AgentTask
agent = FacialVisionAgent(openrouter_api_key="YOUR_API_KEY")
# Full image analysis
task = AgentTask(type="analyze_image", payload={"image_path": "photo.jpg"})
response = agent.process(task)
print(response.data)
Payload formats
The agent accepts two ways to provide the image in the AgentTask payload:
image_path: filesystem path to an image file (e.g."photo.jpg").base64_image: a Base64-encoded string of the image (e.g. when the image is uploaded from a frontend).
Priority and behavior:
- If
base64_imageis present in the payload, the agent will use that string directly. - If only
image_pathis provided, the agent will read the file and convert it to Base64 internally. - If neither field is present, the agent will return an error (the current tests expect the message: "Image path is required").
Examples:
# Using filesystem path (legacy)
task = AgentTask(type="analyze_image", payload={"image_path": "photo.jpg"})
# Using Base64 directly
task = AgentTask(type="analyze_image", payload={"base64_image": "<BASE64_STRING_HERE>"})
Note on Data URIs:
- We recommend sending only the Base64 portion (without the
data:image/…;base64,prefix). If you send a full data URI, strip the prefix before calling the agent.
Testing
Run the test suite locally:
python -m pytest
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-testpypi.yml) is included in this repository. 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.
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.
License
MIT — see the LICENSE file for details.
Metadata
Release files for facial-vision-agent 1.0.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 |
|---|---|---|---|---|
| facial_vision_agent-1.0.0.tar.gz | 13.7 kB | Without provenance | Details for facial_vision_agent-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| facial_vision_agent-1.0.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details for facial_vision_agent-1.0.0-py2.py3-none-any.whl |
Total release size: 23.9 kB
Release files / facial_vision_agent-1.0.0.tar.gz
| Download URL | facial_vision_agent-1.0.0.tar.gz |
|---|---|
| Size | 13.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
363a24067573eb008797a1e163511bdf15b3d0139ebc3c64dd48e7a148030ba2
|
|
BLAKE2b-256 checksum How to use checksums |
124c9d0fc7bb2c30f4554c58d7a2d16a1098610003e96ae839ec2f974f11edd9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / facial_vision_agent-1.0.0-py2.py3-none-any.whl
| Download URL | facial_vision_agent-1.0.0-py2.py3-none-any.whl |
|---|---|
| Size | 10.2 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
3c137cbc8c8890d2937d1c0dc736367ba11677c72b6b368e6e98f7d16f603b69
|
|
BLAKE2b-256 checksum How to use checksums |
a3caa22061e5ef6d61b924667873971c4f6f4ea73c4817a62b98fe02cfaf2958
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for facial-vision-agent 1.0.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.