Adapt Image¶

Adapt Image — mvp.adapt_image

Cluster: Creative & Media | Type: component | MCP Tools: 39

Overview¶

Multi-backend image processing block that handles resize, rotate, crop, flip, brightness/contrast adjustment, format conversion, and basic classification or captioning. Accepts images as base64-encoded strings or URLs and returns results as base64. Backend selection is automatic — Pillow for editing operations, optional vision models for description and labelling — making the block composable at any point in a media pipeline without requiring a specific runtime environment.

When to use:

Resizing or reformatting images before passing them to a ComfyUI or creative-API block
Cropping or rotating images generated by generative art or diffusion pipelines
Adjusting brightness and contrast to normalise inputs for downstream vision models
Converting between PNG, JPEG, WebP, and other formats programmatically

Example:

from mvp.adapt_image import AdaptImageBlock, ImageInput

block = AdaptImageBlock(name="image")
result = block.infer(ImageInput(
    op="resize",
    image_base64="<base64-encoded PNG>",
    width=256,
    height=256,
    format="png",
))
# result.value.image_base64 → resized PNG as base64

Works well with: adapt_comfyui, adapt_generative_art, adapt_creative_api

Public API¶

`ImageOpRecommendation`¶

Validated image op+backend recommendation decision record.

Field	Type	Default
`op`	`str`	required
`backend`	`str`	DEFAULT_BACKEND
`format`	`str`	DEFAULT_FORMAT
`quality_preset`	`str`	DEFAULT_QUALITY_PRESET
`quality`	`int`	DEFAULT_QUALITY
`rationale`	`str`	''
`alternatives`	`list[str]`	field(default_factory=list)
`confidence`	`float`	0.0
`degraded`	`bool`	False
`raw_response`	`str`	''

Methods:

`to_metadata() -> dict[str, Any]`¶

`ImagePlanner`¶

Runtime-first facade with the deterministic floor as honest fallback.

Constructor:

Parameter	Type	Default
`runtime`	`ImageRuntime \\| None`	None

Methods:

`recommend(brief: str, has_image: bool = False) -> ImageOpRecommendation`¶

`AdaptImageBlock(AIBlock[ImageInput, ImageOutput, None])`¶

Image processing block with multi-backend support.

Field	Type	Default
`name`	`str`	'adapt_image'
`resource_bounds`	`ResourceBounds \\| None`	None
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: ImageInput) -> Result[ImageOutput]`¶

`egress_plan(op: str, params: dict) -> 'list[EgressTarget] | None'`¶

`ImageInput(BaseModel)`¶

Input for image processing operations.

Field	Type	Default
`op`	`str`	'resize'
`image_base64`	`str`	''
`image_url`	`str`	''
`brief`	`str`	''
`prompt`	`str`	''
`negative_prompt`	`str`	''
`mask_base64`	`str`	''
`width`	`int`	0
`height`	`int`	0
`format`	`str`	'png'
`quality`	`int`	85
`angle`	`float`	0.0
`crop_box`	`str`	''
`flip_mode`	`str`	''
`brightness`	`float`	1.0
`contrast`	`float`	1.0
`backend`	`str`	''
`native_params`	`dict`	Field(default_factory=dict)
`workflow`	`dict`	Field(default_factory=dict)

`ImageOutput(BaseModel)`¶

Output from image processing operations.

Field	Type	Default
`op`	`str`	required
`image_base64`	`str`	''
`output_path`	`str`	''
`width`	`int`	0
`height`	`int`	0
`format`	`str`	''
`size_bytes`	`int`	0
`backend`	`str`	''
`description`	`str`	''
`labels`	`list[str]`	Field(default_factory=list)
`recommendation`	`dict`	Field(default_factory=dict)
`agentic_evidence`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`degradation`	`dict`	Field(default_factory=dict)
`warnings`	`list[str]`	Field(default_factory=list)
`missing_dependencies`	`list[str]`	Field(default_factory=list)
`unavailable_capabilities`	`list[str]`	Field(default_factory=list)
`usage`	`dict`	Field(default_factory=dict)
`timing`	`dict`	Field(default_factory=dict)
`backend_version`	`str`	''
`provider`	`str`	''
`model`	`str`	''
`workflow_id`	`str`	''
`request_id`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)

`AdaptImageMCPBlock(AIBlock[MCPImageInput, MCPImageOutput, dict])`¶

28-op image MCP block with SQLite persistence.

Field	Type	Default
`name`	`str`	'adapt_image_mcp'
`state`	`dict`	field(default_factory=dict)
`db_path`	`str`	field(default_factory=lambda: os.environ.get('IMAGE_DB_PATH', _DEFAULT_DB))
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: MCPImageInput) -> Result[MCPImageOutput]`¶

`MCPImageRecord(BaseModel)`¶

A single metadata record returned from ImageStore queries.

Field	Type	Default
`id`	`str`	required
`record_type`	`str`	required
`name`	`str`	required
`content`	`str`	required
`tags`	`str`	''
`timestamp`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)

`MCPImageInput(BaseModel)`¶

Input to AdaptImageMCPBlock — 28 ops.

Field	Type	Default
`op`	Literal['generate', 'generate_variations', 'img2img', 'inpaint', 'upscale', 'resize', 'crop', 'rotate', 'flip', 'adjust_color', 'composite', 'convert_format', 'describe', 'classify', 'detect_objects', 'extract_text_ocr', 'encode_base64', 'decode_base64', 'save', 'load', 'list', 'delete', 'list_backends', 'list_models', 'get_info', 'recommend', 'auto', 'list_patterns', 'image_adapter_capabilities', 'pillow_native_capabilities', 'pillow_native_transform', 'comfyui_capabilities', 'comfyui_workflow_validate', 'comfyui_workflow_run', 'comfyui_queue_status', 'comfyui_cancel', 'openrouter_capabilities', 'openrouter_image_generate_native', 'openrouter_vision_native']	required
`image_base64`	`str`	''
`image_url`	`str`	''
`brief`	`str`	''
`prompt`	`str`	''
`negative_prompt`	`str`	''
`mask_base64`	`str`	''
`width`	`int`	0
`height`	`int`	0
`format`	`str`	'png'
`quality`	`int`	85
`angle`	`float`	0.0
`crop_box`	`str`	''
`flip_mode`	`str`	''
`brightness`	`float`	1.0
`contrast`	`float`	1.0
`backend`	`str`	''
`name`	`str`	''
`tags_csv`	`str`	''
`notes`	`str`	''
`limit`	`int`	50
`categories`	`str`	''
`query`	`str`	''
`native_params`	`dict`	Field(default_factory=dict)
`workflow`	`dict`	Field(default_factory=dict)

`MCPImageOutput(BaseModel)`¶

Output from AdaptImageMCPBlock.

Field	Type	Default
`op`	`str`	required
`image_base64`	`str`	''
`output_path`	`str`	''
`width`	`int`	0
`height`	`int`	0
`format`	`str`	''
`size_bytes`	`int`	0
`backend`	`str`	''
`description`	`str`	''
`labels`	`list[str]`	Field(default_factory=list)
`name`	`str`	''
`found`	`bool`	False
`count`	`int`	0
`retrieved`	`list[dict]`	Field(default_factory=list)
`message`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)
`recommendation`	`dict`	Field(default_factory=dict)
`agentic_evidence`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`degradation`	`dict`	Field(default_factory=dict)
`warnings`	`list[str]`	Field(default_factory=list)
`missing_dependencies`	`list[str]`	Field(default_factory=list)
`unavailable_capabilities`	`list[str]`	Field(default_factory=list)
`usage`	`dict`	Field(default_factory=dict)
`timing`	`dict`	Field(default_factory=dict)
`backend_version`	`str`	''
`provider`	`str`	''
`model`	`str`	''
`workflow_id`	`str`	''
`request_id`	`str`	''

`ImageStore`¶

SQLite-backed store for the adapt_image MCP sub-package.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`store_image(name: str, image_b64: str = '', width: int = 0, height: int = 0, fmt: str = 'png', size_bytes: int = 0, tags: str = '', notes: str = '', backend: str = '', metadata: dict | None = None) -> str`¶

Persist a named image. Returns the assigned id.

`retrieve_image(name: str) -> dict | None`¶

Retrieve a stored image by name. Returns None if not found.

`list_images(tags_csv: str = '', limit: int = 50) -> list[dict]`¶

List stored images, optionally filtered by tags.

`delete_image(name: str) -> bool`¶

Delete a stored image by name. Returns True if deleted.

`store_preset(name: str, params: dict, description: str = '', tags: str = '') -> str`¶

Persist a named preset. Returns the assigned id.

`retrieve_preset(name: str) -> dict | None`¶

Retrieve a stored preset by name.

`list_presets(limit: int = 50) -> list[dict]`¶

List stored presets.

`count_all() -> dict[str, int]`¶

Functions¶

`agentic_planner_enabled(default_enabled: bool = True) -> bool`¶

Decide whether the agentic image-op-recommendation planner should be used.

`recommend_image_op_floor(brief: str, has_image: bool = False) -> ImageOpRecommendation`¶

Deterministic keyword/heuristic image-op selector (the demoted floor).

MCP Tools¶

Operation	Source
`generate`	image_mcp
`generate_variations`	image_mcp
`img2img`	image_mcp
`inpaint`	image_mcp
`upscale`	image_mcp
`resize`	image_mcp
`crop`	image_mcp
`rotate`	image_mcp
`flip`	image_mcp
`adjust_color`	image_mcp
`composite`	image_mcp
`convert_format`	image_mcp
`describe`	image_mcp
`classify`	image_mcp
`detect_objects`	image_mcp
`extract_text_ocr`	image_mcp
`encode_base64`	image_mcp
`decode_base64`	image_mcp
`save`	image_mcp
`load`	image_mcp
`list`	image_mcp
`delete`	image_mcp
`list_backends`	image_mcp
`list_models`	image_mcp
`get_info`	image_mcp
`recommend`	image_mcp
`auto`	image_mcp
`list_patterns`	image_mcp
`image_adapter_capabilities`	image_mcp
`pillow_native_capabilities`	image_mcp
`pillow_native_transform`	image_mcp
`comfyui_capabilities`	image_mcp
`comfyui_workflow_validate`	image_mcp
`comfyui_workflow_run`	image_mcp
`comfyui_queue_status`	image_mcp
`comfyui_cancel`	image_mcp
`openrouter_capabilities`	image_mcp
`openrouter_image_generate_native`	image_mcp
`openrouter_vision_native`	image_mcp

Adapt Image¶

Overview¶

Public API¶

ImageOpRecommendation¶

to_metadata() -> dict[str, Any]¶

ImagePlanner¶

recommend(brief: str, has_image: bool = False) -> ImageOpRecommendation¶

AdaptImageBlock(AIBlock[ImageInput, ImageOutput, None])¶

infer(data: ImageInput) -> Result[ImageOutput]¶

egress_plan(op: str, params: dict) -> 'list[EgressTarget] | None'¶

ImageInput(BaseModel)¶

ImageOutput(BaseModel)¶

AdaptImageMCPBlock(AIBlock[MCPImageInput, MCPImageOutput, dict])¶

infer(data: MCPImageInput) -> Result[MCPImageOutput]¶

MCPImageRecord(BaseModel)¶

MCPImageInput(BaseModel)¶

MCPImageOutput(BaseModel)¶

ImageStore¶

store_image(name: str, image_b64: str = '', width: int = 0, height: int = 0, fmt: str = 'png', size_bytes: int = 0, tags: str = '', notes: str = '', backend: str = '', metadata: dict | None = None) -> str¶

retrieve_image(name: str) -> dict | None¶

list_images(tags_csv: str = '', limit: int = 50) -> list[dict]¶

delete_image(name: str) -> bool¶

store_preset(name: str, params: dict, description: str = '', tags: str = '') -> str¶

retrieve_preset(name: str) -> dict | None¶

list_presets(limit: int = 50) -> list[dict]¶

count_all() -> dict[str, int]¶

Functions¶

agentic_planner_enabled(default_enabled: bool = True) -> bool¶

recommend_image_op_floor(brief: str, has_image: bool = False) -> ImageOpRecommendation¶

MCP Tools¶

`ImageOpRecommendation`¶

`to_metadata() -> dict[str, Any]`¶

`ImagePlanner`¶

`recommend(brief: str, has_image: bool = False) -> ImageOpRecommendation`¶

`AdaptImageBlock(AIBlock[ImageInput, ImageOutput, None])`¶

`infer(data: ImageInput) -> Result[ImageOutput]`¶

`egress_plan(op: str, params: dict) -> 'list[EgressTarget] | None'`¶

`ImageInput(BaseModel)`¶

`ImageOutput(BaseModel)`¶

`AdaptImageMCPBlock(AIBlock[MCPImageInput, MCPImageOutput, dict])`¶

`infer(data: MCPImageInput) -> Result[MCPImageOutput]`¶

`MCPImageRecord(BaseModel)`¶

`MCPImageInput(BaseModel)`¶

`MCPImageOutput(BaseModel)`¶

`ImageStore`¶

`store_image(name: str, image_b64: str = '', width: int = 0, height: int = 0, fmt: str = 'png', size_bytes: int = 0, tags: str = '', notes: str = '', backend: str = '', metadata: dict | None = None) -> str`¶

`retrieve_image(name: str) -> dict | None`¶

`list_images(tags_csv: str = '', limit: int = 50) -> list[dict]`¶

`delete_image(name: str) -> bool`¶

`store_preset(name: str, params: dict, description: str = '', tags: str = '') -> str`¶

`retrieve_preset(name: str) -> dict | None`¶

`list_presets(limit: int = 50) -> list[dict]`¶

`count_all() -> dict[str, int]`¶

`agentic_planner_enabled(default_enabled: bool = True) -> bool`¶

`recommend_image_op_floor(brief: str, has_image: bool = False) -> ImageOpRecommendation`¶