Metadata-Version: 2.4
Name: kiarina-agi-image
Version: 2.9.0
Summary: Image detection, embedding, and generation for AI agents
Project-URL: Homepage, https://github.com/kiarina/kiarina-python
Project-URL: Repository, https://github.com/kiarina/kiarina-python
Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-agi-image/CHANGELOG.md
Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-agi-image#readme
Author-email: kiarina <kiarinadawa@gmail.com>
Maintainer-email: kiarina <kiarinadawa@gmail.com>
License-Expression: MIT
Keywords: agents,ai,computer-vision,embeddings,image-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: kiarina-agi-base>=2.7.0
Requires-Dist: kiarina-agi-data>=2.7.0
Requires-Dist: kiarina-agi-file>=2.6.0
Requires-Dist: kiarina-utils-app>=2.4.0
Requires-Dist: kiarina-utils-common>=2.3.0
Requires-Dist: kiarina-utils-file>=2.3.1
Requires-Dist: numpy<3,>=2.0
Requires-Dist: opencv-python<5,>=4.12.0
Requires-Dist: pillow<12,>=11.3.0
Requires-Dist: pydantic-settings-manager>=3.2.0
Requires-Dist: pydantic-settings<3,>=2.10.1
Requires-Dist: pydantic<3,>=2.11.7
Provides-Extra: all
Requires-Dist: google-genai<3,>=1.65.0; extra == 'all'
Requires-Dist: httpx<1,>=0.28.1; extra == 'all'
Requires-Dist: kiarina-lib-google>=2.4.0; extra == 'all'
Requires-Dist: kiarina-lib-openai>=2.3.1; extra == 'all'
Requires-Dist: onnxruntime>=1.25.1; extra == 'all'
Requires-Dist: openai<3,>=2.0.1; extra == 'all'
Provides-Extra: image-detection-provider-dfine
Requires-Dist: onnxruntime>=1.25.1; extra == 'image-detection-provider-dfine'
Provides-Extra: image-detection-provider-yunet
Provides-Extra: image-embedding-provider-gemini
Requires-Dist: google-genai<3,>=1.65.0; extra == 'image-embedding-provider-gemini'
Requires-Dist: kiarina-lib-google>=2.4.0; extra == 'image-embedding-provider-gemini'
Provides-Extra: image-embedding-provider-qwen3-vl
Requires-Dist: httpx<1,>=0.28.1; extra == 'image-embedding-provider-qwen3-vl'
Provides-Extra: image-embedding-provider-sface
Provides-Extra: image-embedding-provider-siglip2
Requires-Dist: onnxruntime>=1.25.1; extra == 'image-embedding-provider-siglip2'
Provides-Extra: image-generation-provider-google
Requires-Dist: google-genai<3,>=1.65.0; extra == 'image-generation-provider-google'
Requires-Dist: kiarina-lib-google>=2.4.0; extra == 'image-generation-provider-google'
Provides-Extra: image-generation-provider-openai
Requires-Dist: httpx<1,>=0.28.1; extra == 'image-generation-provider-openai'
Requires-Dist: kiarina-lib-openai>=2.3.1; extra == 'image-generation-provider-openai'
Requires-Dist: openai<3,>=2.0.1; extra == 'image-generation-provider-openai'
Description-Content-Type: text/markdown

# kiarina-agi-image

English | [日本語](README.ja.md)

[![PyPI](https://img.shields.io/pypi/v/kiarina-agi-image.svg)](https://pypi.org/project/kiarina-agi-image/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)

> [!NOTE] What is this?
> `kiarina-agi-image` provides image detection, embedding, and generation for AI agents.

## Dependencies

### Required Dependencies

| Package | Version | License |
| --- | --- | --- |
| [kiarina-agi-base](../kiarina-agi-base/) | `>=2.7.0` | MIT |
| [kiarina-agi-data](../kiarina-agi-data/) | `>=2.7.0` | MIT |
| [kiarina-agi-file](../kiarina-agi-file/) | `>=2.6.0` | MIT |
| [kiarina-utils-app](../kiarina-utils-app/) | `>=2.4.0` | MIT |
| [kiarina-utils-common](../kiarina-utils-common/) | `>=2.3.0` | MIT |
| [kiarina-utils-file](../kiarina-utils-file/) | `>=2.3.1` | MIT |
| [NumPy](https://github.com/numpy/numpy) | `>=2.0,<3` | BSD-3-Clause |
| [OpenCV](https://github.com/opencv/opencv-python) | `>=4.12.0,<5` | Apache-2.0 |
| [Pillow](https://github.com/python-pillow/Pillow) | `>=11.3.0,<12` | HPND |
| [Pydantic](https://github.com/pydantic/pydantic) | `>=2.11.7,<3` | MIT |
| [pydantic-settings](https://github.com/pydantic/pydantic-settings) | `>=2.10.1,<3` | MIT |
| [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) | `>=3.2.0` | MIT |

### Optional Dependencies

| Package | Extras |
| --- | --- |
| google-genai | `image-embedding-provider-gemini`<br>`image-generation-provider-google` |
| httpx | `image-embedding-provider-qwen3-vl`<br>`image-generation-provider-openai` |
| kiarina-lib-google | `image-embedding-provider-gemini`<br>`image-generation-provider-google` |
| kiarina-lib-openai | `image-generation-provider-openai` |
| onnxruntime | `image-detection-provider-dfine`<br>`image-embedding-provider-siglip2` |
| openai | `image-generation-provider-openai` |

The `all` Extra installs every optional dependency listed above.

## Installation

```bash
pip install kiarina-agi-image
```

To use every provider implementation:

```bash
pip install "kiarina-agi-image[all]"
```

## Features

- **Image Detection**
  Detect objects and faces, crop objects, and align faces.
- **Image Embedding**
  Create image embeddings.
- **Image Generation**
  Generate and edit images with Google, OpenAI, and mock providers.

### Model Cache

YuNet, D-FINE, SFace, and SigLIP2 download their default model on first use when `model_path` is `None`. D-FINE also downloads a verified `config.json` and generates default labels from it when `label_map_path` is `None`.

Files are cached under `user_directory.get_user_cache_dir() / "models" / <implementation>`. An explicit path always takes precedence and prevents downloading the corresponding file.

The default download URL, SHA-256 digest, and cache filename are provider settings and can be overridden through settings, environment variables, or config. When changing the source, also change the filename if an existing cached file should not be reused.

## API Reference

### `kiarina.agi.image_detection_model`

Exports image detection model settings, registries, detection helpers, and cropping helpers.

### `kiarina.agi.image_detection_provider`

Exports the image detection provider protocol, base class, detection result view, and registry.

### `kiarina.agi.image_embedding_model`

Exports image embedding model settings, registry, and embedding helper.

### `kiarina.agi.image_embedding_provider`

Exports the image embedding provider protocol, base class, and registry.

### `kiarina.agi.image_generation_model`

Exports image generation model settings, registry, and generation helper.

### `kiarina.agi.image_generation_provider`

Exports the image generation provider protocol, base class, result view, and registry.

Import provider implementations from the matching `kiarina.agi.*_provider_impl.<name>` path.
