intentkit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

intentkit/skills/venice_image/image_upscale/image_upscale_base.py

@@ -0,0 +1,23 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+# Import the generic base and shared input
+from intentkit.skills.venice_image.base import VeniceImageBaseTool
+from intentkit.skills.venice_image.image_upscale.image_upscale_input import (
+    VeniceImageUpscaleInput,
+)
+
+
+class VeniceImageUpscaleBaseTool(VeniceImageBaseTool):
+    """
+    Base class for Venice AI *Image Upscaling* tools.
+    Inherits from VeniceAIBaseTool and handles specifics of the
+    /image/upscale endpoint
+    """
+
+    args_schema: Type[BaseModel] = VeniceImageUpscaleInput
+    name: str = Field(description="The unique name of the image upscaling tool.")
+    description: str = Field(
+        description="A description of what the image upscaling tool does."
+    )

intentkit/skills/venice_image/image_upscale/image_upscale_input.py

@@ -0,0 +1,22 @@
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+class VeniceImageUpscaleInput(BaseModel):
+    """Input for the Image Upscale tool."""
+
+    image_url: HttpUrl = Field(
+        description="The URL of the image to upscale. Must be a publicly accessible URL.",
+    )
+    replication: Optional[float] = Field(
+        default=0.35,
+        description=(
+            'How strongly lines and noise in the base image are preserved. Higher values are noisier but less plastic/AI "generated"/hallucinated. Must be between 0.1 and 1.'
+            "Required range: 0.1 <= x <= 1"
+        ),
+    )
+    scale: Literal[2, 4] = Field(
+        default=2,
+        description="The factor by which to upscale the image (either 2 or 4). Defaults to 2.",
+    )

intentkit/skills/venice_image/image_vision/README.md

@@ -0,0 +1,112 @@
+# image_vision
+
+**Image Vision** is a sub-tool in the Venice Image suite that provides highly detailed, comprehensive, AI-generated textual descriptions of images. It is designed for analyzing and summarizing the visual content of any image accessible via URL.
+
+---
+
+## What does it do?
+
+This tool uses Venice AI’s latest visual-language model (`qwen-2.5-vl`) to “see” an image as a human or curator would. It returns a paragraph-length, multi-faceted, exhaustive description covering:
+
+- All visible objects and their properties (colors, shapes, count, arrangement)
+- Scene composition: spatial arrangement, relationships, perspective
+- Surface textures, materials, lighting, color palette
+- Contextual, stylistic, or artistic features (e.g., “art deco style,” “digital illustration”)
+- Mood, visual storytelling elements, or any notable anomalies
+- Additional inferred details where possible
+
+This tool is ideal for accessibility, archiving, content discovery, search, and cognitive AI workflows.
+
+---
+
+## Input
+
+| Field        | Type     | Description                                                         | Required |
+|--------------|----------|---------------------------------------------------------------------|----------|
+| image_url    | HttpUrl  | Publicly accessible URL to the target image.                        | Yes      |
+
+Example:
+```json
+{
+  "image_url": "https://example.com/some_picture.jpg"
+}
+```
+
+---
+
+## Example Output
+
+A typical result will be a dictionary with the generated description under a relevant key (the raw API response may vary based on Venice formats):
+
+```json
+{
+  "success": true,
+  "result": "A vibrant, high-resolution digital illustration depicting a Venetian canal at midday. The scene features pastel-hued buildings on either side of the canal with ornate balconies and open shuttered windows. Gondolas and small boats glide over the calm, reflective water, casting rippling shadows. The sky is clear and blue, with sunlight streaming across the facades, creating sharp contrasts and lively reflections. Crowds of tourists are visible on the far bank, while colorful banners and flowerpots accent the architecture. The composition is balanced, with attention to perspective and depth, and the general mood is lively and picturesque."
+}
+```
+
+In case of errors (invalid URL, fetch issues, inappropriate filetype, etc.), a descriptive error message is returned:
+
+```json
+{
+  "success": false,
+  "error": "Failed to fetch or validate image from URL: https://example.com/broken.jpg",
+  "result": null
+}
+```
+
+---
+
+## Typical Use Cases
+
+- **Accessibility:** Generate alt-text for visually impaired users.
+- **AI Agents:** Understand and react to visual content in workflow automations.
+- **Search & Tagging:** Automatically caption and index photo libraries.
+- **Content Moderation:** Pre-screen or context-check image uploads.
+- **Educational Tools:** Explain or transcribe visual materials for students.
+
+---
+
+## Advanced Notes
+
+- The tool only works with image URLs that are publicly accessible and in a common web format (JPG, PNG, etc).
+- Image URLs are validated and, where necessary, format-normalized using Pillow.
+- The system never stores or caches the image, but will download it temporarily for analysis.
+
+**Model Details**  
+Venice AI leverages licensed large vision-language models; this tool currently uses `qwen-2.5-vl`, known for dense, multi-aspect, human-like image explanations.
+
+---
+
+## Configuration Options
+
+- No special options; inherits API key, safe mode, and base logging from the main suite configuration.
+
+---
+
+## Limitations
+
+- May not detect “hidden” content, steganographic messages, or small details lost in low-res images.
+- Will describe as best possible—if the image is blank, corrupted, or unrelated, a best-effort bland description may be given.
+- Not a content moderator—use with your own safety checks if required.
+
+---
+
+## Example Usage (Pseudo-code)
+```python
+result = await agent.send_tool(
+    "image_vision",
+    {
+        "image_url": "https://mycdn.com/image.jpg"
+    }
+)
+desc = result["result"]
+```
+
+---
+
+## Attribution/Compliance
+
+All usage subject to [Venice AI terms of service](https://venice.ai/). Do not use for unlawful or privacy-invading data mining.
+
+---

intentkit/skills/venice_image/image_vision/image_vision.py

@@ -0,0 +1,100 @@
+import logging
+from typing import Any, Type
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, HttpUrl
+
+from intentkit.skills.base import ToolException
+from intentkit.skills.venice_image.image_vision.image_vision_base import (
+    VeniceImageVisionBaseTool,
+)
+from intentkit.skills.venice_image.image_vision.image_vision_input import (
+    VeniceImageVision,
+)
+from intentkit.skills.venice_image.utils import fetch_image_as_base64
+
+logger = logging.getLogger(__name__)
+
+
+class ImageVision(VeniceImageVisionBaseTool):
+    """
+    Describes an image provided via URL using the Venice AI API.
+    Ideal for understanding the content of an existing image.
+    """
+
+    name: str = "venice_image_vision"
+    description: str = (
+        "Describes an image from a URL using Venice AI.\n"
+        "Provide the public URL of the image to describe.\n"
+        "Returns a descriptive text of the image."
+    )
+    args_schema: Type[BaseModel] = VeniceImageVision
+    # No model_id needed for the generic vision endpoint currently
+
+    async def _arun(
+        self,
+        image_url: HttpUrl,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        try:
+            context = self.context_from_config(config)
+
+            await self.apply_venice_rate_limit(context)
+
+            image_base64 = await fetch_image_as_base64(image_url)
+            if not image_base64:
+                error_msg = f"Failed to fetch or validate image from URL: {image_url}"
+                logger.error(error_msg)
+                return {"success": False, "error": error_msg, "result": None}
+
+            payload = {
+                "model": "qwen-2.5-vl",
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "You are an AI model that provides detailed descriptions of images. "
+                                    "When given an image, you must respond with a description that is as comprehensive and detailed as possible. "
+                                    "Focus on identifying all objects, colors, textures, and any other relevant features present in the image. "
+                                    "Provide a thorough and exhaustive account of what is visible in the image."
+                                ),
+                            }
+                        ],
+                    },
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": (
+                                    "Provide an extremely detailed description of the image, focusing on every discernible aspect. "
+                                    "Include information about objects, colors, textures, lighting conditions, artistic style (if applicable), "
+                                    "composition, and any other relevant details that would allow someone to accurately understand and potentially "
+                                    "recreate the image. Be as thorough and comprehensive as possible."
+                                ),
+                            },
+                            {"type": "image_url", "image_url": {"url": str(image_url)}},
+                        ],
+                    },
+                ],
+            }
+
+            result, error = await self.post("api/v1/chat/completions", payload, context)
+            if error:
+                raise ToolException(f"Venice Image Vision API error: {error}")
+            return result
+        except ToolException as e:
+            return {
+                "success": False,
+                "error": f"An unexpected error occurred: {str(e)}",
+            }
+        except Exception as e:
+            logger.error(f"Error in {self.name}: {str(e)}")
+            return {
+                "success": False,
+                "error": f"An unexpected error occurred: {str(e)}",
+            }

intentkit/skills/venice_image/image_vision/image_vision_base.py

@@ -0,0 +1,17 @@
+from pydantic import Field
+
+# Import the generic base and shared input
+from intentkit.skills.venice_image.base import VeniceImageBaseTool
+
+
+class VeniceImageVisionBaseTool(VeniceImageBaseTool):
+    """
+    Base class for Venice AI *Image Vision* tools.
+    Inherits from VeniceAIBaseTool and handles specifics of the
+    /chat/completions endpoint.
+    """
+
+    name: str = Field(description="The unique name of the image vision tool.")
+    description: str = Field(
+        description="A description of what the image vision tool does."
+    )

intentkit/skills/venice_image/image_vision/image_vision_input.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field, HttpUrl
+
+
+class VeniceImageVision(BaseModel):
+    """Input for the Image Vision tool."""
+
+    image_url: HttpUrl = Field(
+        description="The URL of the image to to be described by the Vision model. Must be a publicly accessible URL.",
+    )

intentkit/skills/venice_image/schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Venice Image",
+  "description": "Skills for generating images using the Venice AI API.",
+  "x-icon": "https://ai.service.crestal.dev/skills/venice_image/venice_image.jpg",
+  "x-tags": [
+    "AI",
+    "Image Generation"
+  ],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill category is enabled",
+      "default": false
+    },
+    "states": {
+      "type": "object",
+      "title": "Skill States",
+      "description": "States for each Venice Image skill (disabled, public, or private)",
+      "properties": {
+        "image_vision": {
+          "type": "string",
+          "title": "Image Vision",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Describes an image provided via URL using the Venice AI API. Ideal for understanding the content of an existing image",
+          "default": "public"
+        },
+        "image_enchance": {
+          "type": "string",
+          "title": "Image Enchance",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Tool for **Enchance** (modifying specific areas of) an existing image using a selected image model via Venice AI",
+          "default": "public"
+        },
+        "image_upscale": {
+          "type": "string",
+          "title": "Image Upscale",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Upscale an existing image by 2x or 4x using Venice AI.",
+          "default": "disabled"
+        },
+        "image_generation_flux_dev": {
+          "type": "string",
+          "title": "Image Generation (Flux-Dev)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Venice AI's Flux Dev model (research, art workflows).",
+          "default": "public"
+        },
+        "image_generation_flux_dev_uncensored": {
+          "type": "string",
+          "title": "Image Generation (Flux-Dev-Uncensored)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using the uncensored Flux Dev model (unrestricted, NSFW).",
+          "default": "disabled"
+        },
+        "image_generation_venice_sd35": {
+          "type": "string",
+          "title": "Image Generation (Venice SD3.5)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Stability AI's SD 3.5 Large (art, design).",
+          "default": "disabled"
+        },
+        "image_generation_fluently_xl": {
+          "type": "string",
+          "title": "Image Generation (Fluently-XL)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Fluently-XL (aesthetics, lighting, realism).",
+          "default": "disabled"
+        },
+        "image_generation_lustify_sdxl": {
+          "type": "string",
+          "title": "Image Generation (Lustify-SDXL)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Lustify SDXL (photorealistic, focus on NSFW).",
+          "default": "disabled"
+        },
+        "image_generation_pony_realism": {
+          "type": "string",
+          "title": "Image Generation (Pony-Realism)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Pony Realism (high-detail, realistic, anime/characters).",
+          "default": "disabled"
+        },
+        "image_generation_stable_diffusion_3_5": {
+          "type": "string",
+          "title": "Image Generation (Stable Diffusion 3.5 - Alt ID)",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Generate images using Stability AI's SD 3.5 Large (alternative API ID).",
+          "default": "disabled"
+        }
+      }
+    },
+    "safe_mode": {
+      "type": "boolean",
+      "title": "Safe Mode",
+      "description": "Whether to use safe mode. If enabled, this will blur images that are classified as having adult content",
+      "default": true
+    },
+    "embed_exif_metadata": {
+      "type": "boolean",
+      "title": "Embed Exif Metadata",
+      "description": "Embed prompt generation information into the image's EXIF metadata",
+      "default": false
+    },
+    "hide_watermark": {
+      "type": "boolean",
+      "title": "Hide Watermark",
+      "description": "Whether to hide the Venice watermark. Venice may ignore this parameter for certain generated content.",
+      "default": true
+    },
+    "negative_prompt": {
+      "type": "string",
+      "title": "Default Negative Prompt",
+      "description": "Default negative prompt to use if none is provided in the skill call.",
+      "default": "(worst quality: 1.4), bad quality, nsfw"
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Provider of the API key for AIXBT API service",
+      "enum": [
+        "agent_owner"
+      ],
+      "x-enum-title": [
+        "Owner Provided"
+      ],
+      "default": "agent_owner"
+    }
+  },
+  "required": [
+    "states",
+    "enabled"
+  ],
+  "if": {
+    "properties": {
+      "api_key_provider": {
+        "const": "agent_owner"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "api_key": {
+        "type": "string",
+        "title": "Venice API Key",
+        "x-link": "[Get your API key](https://venice.ai/)",
+        "x-sensitive": true,
+        "description": "Optional API key for Venice AI services. If not provided, the system key will be used."
+      },
+      "rate_limit_number": {
+        "type": "integer",
+        "title": "Rate Limit Number",
+        "description": "Number of requests allowed per time window. Only applies if using an agent-specific API key."
+      },
+      "rate_limit_minutes": {
+        "type": "integer",
+        "title": "Rate Limit Minutes",
+        "description": "Time window in minutes for rate limiting. Only applies if using an agent-specific API key."
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_key"
+      ]
+    }
+  },
+  "additionalProperties": true
+}

intentkit/skills/venice_image/utils.py

@@ -0,0 +1,78 @@
+import base64
+import io
+import logging
+from typing import Optional
+
+import filetype
+import httpx
+from PIL import Image
+from pydantic import HttpUrl
+
+from intentkit.skills.base import ToolException
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_image_as_bytes(image_url: HttpUrl) -> bytes:
+    """Fetches image bytes from a given URL. Converts unsupported formats to PNG using Pillow.
+
+    Raises:
+        ToolException: If fetching or converting the image fails.
+    """
+    try:
+        async with httpx.AsyncClient(timeout=90) as client:
+            response = await client.get(str(image_url), follow_redirects=True)
+            response.raise_for_status()
+
+            original_bytes = response.content
+
+            # Guess file type from content
+            kind = filetype.guess(original_bytes)
+            detected_ext = kind.extension if kind else None
+            detected_mime = kind.mime if kind else "unknown"
+
+            if not detected_ext or not detected_mime.startswith("image/"):
+                msg = f"URL {image_url} did not return a recognizable image format. Detected: {detected_mime}"
+                logger.error(msg)
+                raise ToolException(msg)
+
+            if detected_ext in ("jpg", "jpeg", "png"):
+                return original_bytes
+
+            # Convert unsupported image to PNG
+            try:
+                img = Image.open(io.BytesIO(original_bytes)).convert("RGBA")
+                with io.BytesIO() as output:
+                    img.save(output, format="PNG")
+                    logger.info(
+                        f"Converted unsupported image type '{detected_ext}' to PNG."
+                    )
+                    return output.getvalue()
+            except Exception as e:
+                msg = f"Failed to convert image ({detected_ext}) to PNG: {e}"
+                logger.error(msg, exc_info=True)
+                raise ToolException(msg) from e
+
+    except httpx.HTTPStatusError as e:
+        msg = f"HTTP error fetching image {image_url}: Status {e.response.status_code}"
+        logger.error(msg)
+        raise ToolException(msg) from e
+    except httpx.RequestError as e:
+        msg = f"Network error fetching image {image_url}: {e}"
+        logger.error(msg)
+        raise ToolException(msg) from e
+    except Exception as e:
+        msg = f"Unexpected error fetching image {image_url}: {e}"
+        logger.error(msg, exc_info=True)
+        raise ToolException(msg) from e
+
+
+async def fetch_image_as_base64(image_url: HttpUrl) -> Optional[str]:
+    """Fetches an image from the URL and returns the image as a Base64-encoded string."""
+    image_bytes = await fetch_image_as_bytes(image_url)
+
+    if image_bytes is None:
+        return None
+
+    # Convert image bytes to a Base64-encoded string
+    return base64.b64encode(image_bytes).decode("utf-8")