hermes-mai-image 0.2.0__tar.gz

hermes_mai_image-0.2.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

hermes_mai_image-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - name: Install test dependencies
+        run: python -m pip install -e '.[test,lint]'
+      - name: Lint
+        run: ruff check src tests
+      - name: Run tests
+        run: python -m pytest -q
+      - name: Compile Python
+        run: python -m compileall -q src tests
+      - name: Build wheel
+        run: python -m pip wheel --no-deps --wheel-dir dist .
+      - name: Verify plugin.yaml is in the wheel
+        run: python -m zipfile -l dist/*.whl | grep plugin.yaml
+
+  catalog-validation:
+    # Validates the plugin against Hermes' own plugin validator, which is the gate the
+    # Hermes plugin catalog applies. Hermes must be installed for this to run, so it is a
+    # separate job that pins a Hermes version rather than pulling it into the test matrix.
+    #
+    # The plugin manifest lives at src/hermes_mai_image/plugin.yaml, so the validator must
+    # target that directory. Validating the repository root fails with
+    # "no plugin.yaml (or portable plugin.json) in the plugin directory".
+    #
+    # Reproduce locally with the Hermes CLI on PATH:
+    #   hermes plugins validate src/hermes_mai_image
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - name: Install Hermes (pinned release tag)
+        # Pinned so catalog validation is deterministic; bump deliberately. Hermes is not
+        # installable from PyPI (the published hermes-agent is stale) and refuses wheel
+        # builds, so clone the release tag and install it editable, as Hermes itself does.
+        env:
+          HERMES_REF: v2026.9.24
+        run: |
+          git clone --depth 1 --branch "$HERMES_REF" https://github.com/NousResearch/hermes-agent.git "$RUNNER_TEMP/hermes-agent"
+          python -m pip install -e "$RUNNER_TEMP/hermes-agent"
+      - name: Validate plugin manifest
+        run: hermes plugins validate src/hermes_mai_image

hermes_mai_image-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build twine
+          python -m build
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+      - name: Verify plugin.yaml is in the wheel
+        run: python -m zipfile -l dist/*.whl | grep plugin.yaml
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing (OIDC); no stored token
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

hermes_mai_image-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+# Virtual environments
+.venv/
+venv/
+
+# Build and packaging output
+dist/
+build/
+*.egg-info/
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+# Local environment files
+.env

hermes_mai_image-0.2.0/AGENTS.md

@@ -0,0 +1,128 @@
+---
+name: hermes-mai-image
+description: "Repository guidance for the standalone Hermes Agent Microsoft Foundry MAI image-generation plugin."
+---
+
+# Hermes MAI Image Plugin
+
+## Purpose
+
+This repository contains a standalone Hermes Agent image-generation provider for Microsoft Foundry MAI image models. It is distributed from GitHub and is designed to become a PyPI package later.
+
+## Repository layout
+
+- `src/hermes_mai_image/provider.py` — provider implementation, model discovery, generation, editing, response handling, and cache integration.
+- `src/hermes_mai_image/plugin.yaml` — Hermes plugin metadata.
+- `src/hermes_mai_image/__init__.py` — public package exports and the module-level `register` hook.
+- `tests/test_mai_image_plugin.py` — mocked HTTP contract tests; tests never use live Azure credentials.
+- `README.md` — installation, configuration, Web UI, CLI, troubleshooting, and update instructions.
+- `pyproject.toml` — package metadata, dependencies, test extra, and the `hermes_agent.plugins` entry point.
+
+## Hermes plugin contract
+
+The package must keep this entry point format:
+
+```toml
+[project.entry-points."hermes_agent.plugins"]
+azure-mai-image = "hermes_mai_image"
+```
+
+Hermes discovers this provider as a module import. Do not change it to `hermes_mai_image:register` without verifying Hermes' provider discovery contract; that target is treated differently by Hermes and previously caused the provider not to appear in `hermes tools`.
+
+The provider identity is:
+
+- Name: `azure-mai`
+- Display name: `Microsoft Foundry MAI`
+- Plugin key: `azure-mai-image`
+
+The module-level `register(ctx)` function calls `ctx.register_image_gen_provider(MAIImageProvider())`.
+
+## API contract
+
+Use Microsoft Foundry's native MAI API, not the standard OpenAI image API:
+
+- Generation: `POST {endpoint}/mai/v1/images/generations`
+- Editing: `POST {endpoint}/mai/v1/images/edits`
+- Authentication: `api-key` request header
+- Generation JSON fields: `model`, `prompt`, `width`, `height`
+- Editing: multipart form fields `model`, `prompt`, and `image`
+
+The configured endpoint is the resource root, such as `https://resource.services.ai.azure.com`. The provider appends `/mai/v1`; never require users to enter that suffix.
+
+Required credentials/settings:
+
+- `MAI_FOUNDRY_API_KEY` — secret; store in the active Hermes profile `.env` only.
+- `MAI_FOUNDRY_ENDPOINT` — Foundry resource root.
+- `MAI_IMAGE_MODEL` — optional deployment/model override; the exact Foundry deployment name is preferred.
+- `MAI_FOUNDRY_MODELS_PATH` — optional discovery path override, default `/models`.
+
+Never place credentials in source, tests, `config.yaml`, README examples, commits, logs, or chat messages.
+
+## Development workflow
+
+Work on a feature branch, not directly on `main`:
+
+```bash
+git switch main
+git pull --ff-only origin main
+git switch -c feature/<short-description>
+```
+
+Create a local environment and install test dependencies:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e '.[test]'
+```
+
+Run the focused suite:
+
+```bash
+python -m pytest -q
+python -m compileall -q src tests
+```
+
+Build a wheel before packaging changes:
+
+```bash
+python -m pip wheel --no-deps --wheel-dir dist .
+```
+
+## Testing rules
+
+- Keep HTTP tests mocked; no test should require or transmit a real Azure key.
+- Test request URLs, headers, payload shapes, multipart edit fields, response parsing, missing credentials, and cache materialization.
+- Follow red-green-refactor for behavior changes: write a failing test first, confirm the expected failure, implement the smallest fix, then run the full suite.
+- Do not weaken tests to accommodate an implementation error.
+
+For live validation, use a separately configured Hermes profile and explicit user-provided credentials. Never add live credentials to test fixtures or CI.
+
+## Release and distribution
+
+The primary installation path is the GitHub URL:
+
+```bash
+pip install --upgrade "git+https://github.com/joescars/hermes-mai-image.git"
+```
+
+After changing package metadata or provider code:
+
+1. Run tests, compilation, and wheel build.
+2. Review `git diff --check` and the staged file list.
+3. Commit with a focused message.
+4. Push the feature branch and open a PR unless the user explicitly asks to work directly on `main`.
+5. After merge, verify the GitHub default branch contains the commit.
+
+If the Hermes Python virtual environment is replaced by a Hermes update, users may need to reinstall the package into the new environment. Profile credentials and configuration are separate and should not be deleted by a plugin release.
+
+## Documentation requirements
+
+Update `README.md` when installation, configuration, endpoints, provider discovery, or update behavior changes. Keep the CLI and Web UI steps accurate. Explicitly state that the endpoint is the resource root and that `/mai/v1` is appended by the provider.
+
+## Safety boundaries
+
+- Do not modify Hermes core for provider-specific behavior.
+- Do not add unauthenticated live API calls to tests or build steps.
+- Do not print API keys, authorization headers, or full credential-bearing URLs.
+- Do not use destructive Git commands (`reset --hard`, unapproved stash, broad clean) to resolve unrelated local changes.

hermes_mai_image-0.2.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.2.0] - 2026-11-15
+
+### Added
+
+- Opt-in MAI-Image-2.6 `auto_aspect_ratio` and `web_grounding` options (config keys under
+  `image_gen.azure-mai` or `MAI_AUTO_ASPECT_RATIO` / `MAI_WEB_GROUNDING`), sent on generation and
+  edits only when enabled and skipped with a warning on non-2.6 deployments; `web_grounding` is
+  disclosed in the README and catalog. (#22)
+- Image edits accept up to five reference images (repeated multipart `image` fields, in order), with
+  per-source checks, a total upload cap, and rejection of more than five before any request (#21).
+- Model picker lists the configured deployment first (de-duplicated, bare id) and labels fallback
+  entries as model names that must match your deployment name; README documents best-effort discovery and
+  `az` deployment listing. (#27)
+- Endpoint normalization and validation: pasted `/mai/v1`, `/models`, `/openai/v1` and project URL
+  suffixes resolve to the resource root, bare hosts get `https://`, non-https endpoints fail with
+  `invalid_config` without a request, and model discovery is skipped without credentials.
+- Credential resolution through the Hermes secret scope, so provider settings are read from the
+  active profile's secret store instead of ambient environment lookup.
+- An in-plugin, SSRF-safe image downloader that validates reference image URLs with the published
+  `tools.url_safety.is_safe_url` before fetching them. Local reference files are still checked with
+  the private `agent.file_safety.raise_if_read_blocked` import (documented in the README; tracked by #7).
+- A draft catalog entry under `catalog/` for submission to the Hermes plugin catalog.
+
+### Changed
+
+- Source images stream into memory (no temp file), local files are size-checked via `stat` before reading, `MAX_REMOTE_IMAGE_BYTES` is renamed `MAX_SOURCE_IMAGE_BYTES`, and the contradictory `agent.file_safety` comment is fixed.
+
+
+- CI hardening: ruff lint, Python 3.13/3.14 matrix, SHA-pinned actions, Dependabot, wheel `plugin.yaml` check, a tag-triggered PyPI Trusted Publishing release workflow, and SPDX license metadata (#29).
+- Image sizes are now model-aware: MAI-Image-2.5 models use presets within the 1,048,576-pixel limit
+  (landscape `1248x832`, portrait `832x1248`); 2.6 deployments (detected from the name, or via
+  `MAI_IMAGE_SIZE_PROFILE` / `image_gen.azure-mai.size_profile` = `2.5`/`2.6`) use larger presets. (#17)
+- Safer retry policy: 429 is always retried honouring `Retry-After` (seconds or HTTP-date) with a
+  long jittered backoff otherwise; only 502/503 are retried among 5xx (never 500/504, to avoid
+  double billing); retries share an overall `MAI_REQUEST_DEADLINE` budget (default 600s).
+- Honor Hermes secret scope for `MAI_FOUNDRY_API_KEY` (no env fallback inside Hermes); endpoint is a non-secret setting resolvable from `image_gen.azure-mai.*` config or env, and model/models-path are declared optional (#25).
+- HTTP error messages are now accurate per status: 400 reports a rejected request (with the service
+  `error.code`/`message` and size/format limits) instead of a missing deployment, 404 covers deployment/endpoint,
+  401/403 give authentication guidance, 429 mentions quota tiers, and detail is truncated to ~500 characters (#18).
+- GIF and WebP source images are now rejected before upload with `invalid_input` (MAI accepts only
+  JPEG or PNG); README and catalog known issues list the supported formats.
+- Security: remote source-image downloads no longer follow redirects (`allow_redirects=False`; 3xx and redirect history are rejected), closing an SSRF bypass (#19).
+- Provider robustness: model discovery no longer raises when the resource `/models` endpoint is
+  unavailable, falling back to the documented MAI catalog.
+- Provider robustness: remote image downloads enforce a byte cap to bound memory use.
+- Runtime dependency is bounded: `requests>=2.28,<3` (catalog rule 10 asks for a floor and an upper bound).
+- Manifest metadata completed; `pyproject.toml` and `plugin.yaml` declare the same version, enforced
+  by a test that parses both.
+- README updated for catalog submission (installation, configuration, and discovery instructions).
+
+## [0.1.2]
+
+### Changed
+
+- README installation, configuration, Web UI, CLI, troubleshooting, and update instructions
+  refreshed for the current Hermes plugin discovery flow.
+
+[Unreleased]: https://github.com/joescars/hermes-mai-image/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/joescars/hermes-mai-image/releases/tag/v0.2.0
+[0.1.2]: https://github.com/joescars/hermes-mai-image/releases/tag/v0.1.2

hermes_mai_image-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joescars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.