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

intentkit/skills/venice_image/base.py

@@ -0,0 +1,188 @@
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+from pydantic import Field
+
+from intentkit.abstracts.skill import SkillStoreABC
+from intentkit.skills.base import (
+    IntentKitSkill,
+    SkillContext,
+    ToolException,
+)
+from intentkit.skills.venice_image.api import (
+    make_venice_api_request,
+)
+from intentkit.skills.venice_image.config import VeniceImageConfig
+
+logger = logging.getLogger(__name__)
+
+venice_base_url = "https://api.venice.ai"  # Common base URL for all Venice endpoints
+
+
+class VeniceImageBaseTool(IntentKitSkill):
+    """
+    Base class for all Venice AI image-related skills.
+
+    This class provides common functionality for interacting with the
+    Venice AI API, including:
+
+    -   Retrieving the API key (from agent or system configuration).
+    -   Applying rate limits to prevent overuse of the API.
+    -   A standardized `post` method for making API requests.
+
+    Subclasses should inherit from this class and implement their specific
+    API interactions (e.g., image generation, upscaling, inpainting)
+    by defining their own `_arun` methods and setting appropriate `name`
+    and `description` attributes.
+    """
+
+    @property
+    def category(self) -> str:
+        """
+        Returns the category of this skill, used for configuration and logging.
+        """
+        return "venice_image"
+
+    skill_store: SkillStoreABC = Field(
+        description="The skill store for persisting data and configs."
+    )
+
+    def getSkillConfig(self, context: SkillContext) -> VeniceImageConfig:
+        """
+        Creates a VeniceImageConfig instance from a dictionary of configuration values.
+
+        Args:
+            config: A dictionary containing configuration settings.
+
+        Returns:
+            A VeniceImageConfig object.
+        """
+
+        return VeniceImageConfig(
+            api_key_provider=context.config.get("api_key_provider", "agent_owner"),
+            safe_mode=context.config.get("safe_mode", True),
+            hide_watermark=context.config.get("hide_watermark", True),
+            embed_exif_metadata=context.config.get("embed_exif_metadata", False),
+            negative_prompt=context.config.get(
+                "negative_prompt", "(worst quality: 1.4), bad quality, nsfw"
+            ),
+            rate_limit_number=context.config.get("rate_limit_number"),
+            rate_limit_minutes=context.config.get("rate_limit_minutes"),
+        )
+
+    def get_api_key(self, context: SkillContext) -> str:
+        """
+        Retrieves the Venice AI API key based on the api_key_provider setting.
+
+        Returns:
+            The API key if found.
+
+        Raises:
+            ToolException: If the API key is not found or provider is invalid.
+        """
+        try:
+            skillConfig = self.getSkillConfig(context=context)
+            if skillConfig.api_key_provider == "agent_owner":
+                agent_api_key = context.config.get("api_key")
+                if agent_api_key:
+                    logger.debug(
+                        f"Using agent-specific Venice API key for skill {self.name} in category {self.category}"
+                    )
+                    return agent_api_key
+                raise ToolException(
+                    f"No agent-owned Venice API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            elif skillConfig.api_key_provider == "platform":
+                system_api_key = self.skill_store.get_system_config("venice_api_key")
+                if system_api_key:
+                    logger.debug(
+                        f"Using system Venice API key for skill {self.name} in category {self.category}"
+                    )
+                    return system_api_key
+                raise ToolException(
+                    f"No platform-hosted Venice API key found for skill '{self.name}' in category '{self.category}'."
+                )
+
+            else:
+                raise ToolException(
+                    f"Invalid API key provider '{skillConfig.api_key_provider}' for skill '{self.name}'"
+                )
+
+        except Exception as e:
+            raise ToolException(f"Failed to retrieve Venice API key: {str(e)}") from e
+
+    async def apply_venice_rate_limit(self, context: SkillContext) -> None:
+        """
+        Applies rate limiting to prevent exceeding the Venice AI API's rate limits.
+
+        Rate limits are applied based on the api_key_provider setting:
+            - 'agent_owner': uses agent-specific configuration.
+            - 'platform': uses system-wide configuration.
+        """
+        try:
+            user_id = context.user_id
+            skillConfig = self.getSkillConfig(context=context)
+
+            if skillConfig.api_key_provider == "agent_owner":
+                limit_num = skillConfig.rate_limit_number
+                limit_min = skillConfig.rate_limit_minutes
+
+                if limit_num and limit_min:
+                    logger.debug(
+                        f"Applying Agent rate limit ({limit_num}/{limit_min} min) for user {user_id} on {self.name}"
+                    )
+                    await self.user_rate_limit_by_category(
+                        user_id, limit_num, limit_min
+                    )
+
+            elif skillConfig.api_key_provider == "platform":
+                system_limit_num = self.skill_store.get_system_config(
+                    f"{self.category}_rate_limit_number"
+                )
+                system_limit_min = self.skill_store.get_system_config(
+                    f"{self.category}_rate_limit_minutes"
+                )
+
+                if system_limit_num and system_limit_min:
+                    logger.debug(
+                        f"Applying System rate limit ({system_limit_num}/{system_limit_min} min) for user {user_id} on {self.name}"
+                    )
+                    await self.user_rate_limit_by_category(
+                        user_id, system_limit_num, system_limit_min
+                    )
+            # do nothing if no rate limit is
+            return None
+
+        except Exception as e:
+            raise ToolException(f"Failed to apply Venice rate limit: {str(e)}") from e
+
+    async def post(
+        self, path: str, payload: Dict[str, Any], context: SkillContext
+    ) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
+        """
+        Makes a POST request to the Venice AI API using the `make_venice_api_request`
+        function from the `skills.venice_image.api` module.
+
+        This method handles the following:
+
+        1.  Retrieving the API key using `get_api_key`.
+        2.  Constructing the request payload.
+        3.  Calling `make_venice_api_request` to make the actual API call.
+        4.  Returning the results from `make_venice_api_request`.
+
+        Args:
+            path: The API endpoint path (e.g., "/api/v1/image/generate").
+            payload: The request payload as a dictionary.
+            context: The SkillContext for accessing API keys and configs.
+
+        Returns:
+            A tuple: (success_data, error_data).
+            - If successful, success contains the JSON response from the API.
+            - If an error occurs, success is an empty dictionary, and error contains error details.
+        """
+        api_key = self.get_api_key(context)
+
+        return await make_venice_api_request(
+            api_key, path, payload, self.category, self.name
+        )

intentkit/skills/venice_image/config.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class VeniceImageConfig(BaseModel):
+    """Skill Config for Venice Image."""
+
+    api_key_provider: str = Field(
+        default="agent_owner",
+        description="Provider of the API Key, could be agent_owner or platform",
+    )
+    safe_mode: bool = Field(
+        default=True,
+        description="Whether to use safe mode. If enabled, this will blur images that are classified as having adult content",
+    )
+    hide_watermark: bool = Field(
+        default=True,
+        description="Whether to hide the Venice watermark. Venice may ignore this parameter for certain generated content.",
+    )
+    embed_exif_metadata: bool = Field(
+        default=False, description="Whether to embed EXIF metadata in the image."
+    )
+    negative_prompt: str = Field(
+        default="(worst quality: 1.4), bad quality, nsfw",
+        description="The default negative prompt used when no other prompt is provided.",
+    )
+    rate_limit_number: Optional[int] = Field(
+        default=None,
+        description="Maximum number of allowed calls within the specified time window.",
+    )
+    rate_limit_minutes: Optional[int] = Field(
+        default=None,
+        description="Duration of the time window (in minutes) for rate limiting.",
+    )

intentkit/skills/venice_image/image_enhance/README.md

@@ -0,0 +1,119 @@
+# image_enhance
+
+**Image Enhance** enables you to improve, stylize, or refine an existing image using the Venice AI enhancer. Unlike upscaling, this tool keeps the original image size but substantially upgrades its visual quality, style, or texture—ideal for creative, restoration, or polishing use-cases.
+
+---
+
+## What does it do?
+
+- Accepts a publicly accessible image URL.
+- Uses a provided prompt to guide the desired enhancement—e.g., style, artistic direction, or quality upgrades (such as “gold accents”, “vivid color”, “oil painting”, or “gentle watercolor”).
+- Supports adjustment of the intensity of enhancement and how much original detail is preserved (creativity & replication).
+- Returns a new image (matching original dimensions) with enhanced appearance and style.
+
+Typical uses:
+- Sharpen and clarify blurry images.
+- Instantly “re-theme” a photo or artwork (color, material, style transfer).
+- Polish images for social, ecommerce, professional, or creative projects.
+
+---
+
+## Input Parameters
+
+| Field             | Type          | Description                                                                                                      | Required | Default |
+|-------------------|---------------|------------------------------------------------------------------------------------------------------------------|----------|---------|
+| image_url         | str (HttpUrl) | Publicly accessible URL of the image to enhance                                                                  | Yes      |         |
+| enhancePrompt     | str           | **Describes the desired enhancement, style, or theme.** Concise, descriptive terms work best.                    | Yes      |         |
+| replication       | float         | How much of the original image structure, lines, and noise are retained (0.1–1.0).                               | No       | 0.35    |
+| enhanceCreativity | float         | How far the AI can diverge from the original (0 = subtle, 1 = max stylization/new image).                        | No       | 0.5     |
+
+**Prompt Examples (for `enhancePrompt`):**
+- `"marble, gold veins, high contrast"`
+- `"vaporwave color palette, cyberpunk lighting"`
+- `"oil painting, impasto brushwork"`
+- `"smooth skin, brighten shadows, cinematic look"`
+
+Example input:
+```json
+{
+  "image_url": "https://img.site/old-photo.png",
+  "enhancePrompt": "soft watercolor, pastel tones, gentle light",
+  "replication": 0.25,
+  "enhanceCreativity": 0.7
+}
+```
+
+---
+
+## Output
+
+On success, returns:
+```json
+{
+  "success": true,
+  "result": "https://s3.storage.example/venice_image/image_enhance/ab12cd...png"
+}
+```
+
+On error:
+```json
+{
+  "success": false,
+  "error": "Failed to fetch or validate image from URL: ...",
+  "result": null
+}
+```
+
+---
+
+## Typical Use Cases
+
+- **Commerce/Product Images**: Instantly polish web photos for catalogs or listings.
+- **Restoration**: Revive faded or dated artwork/photos for social, framing, or print.
+- **Style Transfer**: Make a photo look like “stained glass”, “anime cel”, or “movie still”.
+- **Social & Art Creation**: Quickly freshen up images for sharing with a unique twist.
+
+---
+
+## Advanced Notes
+
+- **Replication**:  
+  - Lower (`~0.1`): AI smooths out noise/details, crisper/cleaner look.
+  - Higher (`~0.9`): Retain original grit, preserve realistic features, more subtle change.
+- **EnhanceCreativity**:  
+  - Lower (`0.0`): Only very minor tweaks.
+  - Higher (`1.0`): Might look like a fully new artwork in the target style.
+- **Image must be accessible and in a supported format**; conversion to PNG is automatic if needed.
+- **Original resolution is kept**; for larger output, use `image_upscale` after enhancement.
+
+---
+
+## Limitations
+
+- Does not increase resolution—use in conjunction with upscaling for large deliverables.
+- Not a restoration-of-lost-content tool: Real degradation or loss isn’t recoverable, though apparent fidelity can be improved.
+- The style quality depends on the provided enhancement prompt and the source image clarity.
+
+---
+
+## Example Usage (Python-esque pseudocode)
+
+```python
+result = await agent.send_tool(
+    "image_enhance",
+    {
+        "image_url": "https://cdn.site/photo.jpg",
+        "enhancePrompt": "marble, gold details, glowing edges",
+        "enhanceCreativity": 0.9
+    }
+)
+enhanced_url = result["result"]
+```
+
+---
+
+## Attribution & Compliance
+
+Use of this tool is subject to [Venice AI terms of service](https://venice.ai/) and applicable copyright law for input images.
+
+---

intentkit/skills/venice_image/image_enhance/image_enhance.py

@@ -0,0 +1,80 @@
+import logging
+from typing import Optional
+
+from langchain_core.runnables import RunnableConfig
+from pydantic import HttpUrl
+
+from intentkit.skills.base import ToolException
+from intentkit.skills.venice_image.image_enhance.image_enhance_base import (
+    VeniceImageEnhanceBaseTool,
+)
+from intentkit.skills.venice_image.utils import fetch_image_as_base64
+
+logger = logging.getLogger(__name__)
+
+
+class ImageEnhance(VeniceImageEnhanceBaseTool):
+    """
+    Enhances an existing image provided via URL using the Venice AI enhancer (not upscaling).
+    Useful for improving visual quality, adding style, or refining image features.
+    """
+
+    name: str = "venice_image_enhance"
+    description: str = (
+        "Enhances an existing image from a URL using Venice AI.\n"
+        "Provide the public URL of the image to enhance.\n"
+        "Specify enhancement creativity level and a required prompt for style.\n"
+        "Returns the URL of the enhanced image."
+    )
+
+    async def _arun(
+        self,
+        image_url: HttpUrl,
+        enhancePrompt: str,
+        replication: Optional[float] = 0.35,
+        enhanceCreativity: Optional[float] = 0.5,
+        config: RunnableConfig = None,
+        **kwargs,
+    ) -> dict:
+        """
+        Applies AI enhancement to an image without changing its size.
+        """
+
+        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)
+                raise ToolException(
+                    str({"success": False, "error": error_msg, "result": None})
+                )
+
+            payload = {
+                "image": image_base64,
+                "scale": 1,
+                "enhance": True,
+                "replication": replication,
+                "enhanceCreativity": enhanceCreativity,
+                "enhancePrompt": enhancePrompt,
+            }
+
+            result, error = await self.post("api/v1/image/upscale", payload, context)
+            if error:
+                raise ToolException(f"Venice Image Enhance API error: {error}")
+            return result
+        except ToolException as e:
+            raise e
+        except Exception as e:
+            logger.error(f"Error in {self.name}: {str(e)}")
+            raise ToolException(
+                str(
+                    {
+                        "success": False,
+                        "error": f"An unexpected error occurred: {str(e)}",
+                    }
+                )
+            )

intentkit/skills/venice_image/image_enhance/image_enhance_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_enhance.image_enhance_input import (
+    VeniceImageEnhanceInput,
+)
+
+
+class VeniceImageEnhanceBaseTool(VeniceImageBaseTool):
+    """
+    Base class for Venice AI *Image Enchanching* tools.
+    Inherits from VeniceAIBaseTool and handles specifics of the
+    /image/upscale endpoint
+    """
+
+    args_schema: Type[BaseModel] = VeniceImageEnhanceInput
+    name: str = Field(description="The unique name of the image Enchanching tool.")
+    description: str = Field(
+        description="A description of what the image Enchanching tool does."
+    )

intentkit/skills/venice_image/image_enhance/image_enhance_input.py

@@ -0,0 +1,40 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class VeniceImageEnhanceInput(BaseModel):
+    """Input for Venice Image Enhance tool (scale=1, enhance=True)."""
+
+    image_url: str = Field(
+        description="The URL of the image to enhance. Must be a publicly accessible URL."
+    )
+
+    enhancePrompt: str = Field(
+        ...,
+        max_length=1500,
+        description=(
+            "Required prompt describing the desired enhancement style. "
+            "Best used with short descriptors like 'gold', 'marble', or 'angry, menacing'."
+        ),
+    )
+
+    replication: Optional[float] = Field(
+        default=0.35,
+        ge=0.1,
+        le=1.0,
+        description=(
+            "How strongly lines and noise in the base image are preserved. "
+            "Higher values retain more noise and detail but are less smooth."
+        ),
+    )
+
+    enhanceCreativity: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "How much the enhancement AI is allowed to change the image. "
+            "0 = minimal change, 1 = generate a new image entirely."
+        ),
+    )

intentkit/skills/venice_image/image_generation/README.md

@@ -0,0 +1,144 @@
+# Venice Image Generation Tools
+
+Venice Image Generation provides flexible, prompt-based image creation using multiple state-of-the-art AI models via the Venice AI API. These tools support a broad spectrum of styles, subject matter, and output formats, making it ideal for artists, designers, marketers, research, and personal creativity.
+
+---
+
+## Overview
+
+- **Purpose:** Synthesize original images from natural-language prompts.
+- **Supported Models:** Choose from several world-class models, each suited for different tasks:
+    - **Fluently XL:** Professional realism, lighting, artistic work.
+    - **Flux Dev:** Artistic research, innovative and creative workflows.
+    - **Flux Dev Uncensored:** For unrestricted, uncensored generation (including NSFW).
+    - **Lustify SDXL:** Photorealistic, NSFW/SFW versatility.
+    - **Pony Realism:** High-detail anime/character design (great with Danbooru tags).
+    - **Venice SD35/Stable Diffusion 3.5:** Artistic, illustrative, or design content, powered by Stability AI.
+- **Unified Interface:** Each model is its own sub-tool, but all support the same core set of options.
+
+---
+
+## Input Parameters
+
+| Field            | Type                            | Description                                                                                            | Required | Default        |
+|------------------|---------------------------------|--------------------------------------------------------------------------------------------------------|----------|---------------|
+| prompt           | string                          | Main description of the image to generate. Use detailed, specific language for best results.           | Yes      |               |
+| model_id         | string (see below)              | AI model to use. Each sub-tool sets its own model_id internally.                                       | N/A      | (hardcoded)    |
+| width            | int (max 2048)                  | Output image width (pixels). Must be multiple of 8 or 16 depending on model.                           | No       | 1024          |
+| height           | int (max 2048)                  | Output image height (pixels).                                                                          | No       | 1024          |
+| format           | "png" \| "jpeg" \| "webp"       | Output image format.                                                                                   | No       | png           |
+| style_preset     | string (enumerated)             | Optional visual preset (e.g., "Photographic", "Anime", "Abstract", etc.). See full list below.         | No       | Photographic   |
+| negative_prompt  | string                          | Exclude these elements or concepts from the image (e.g. “nsfw, low quality”).                          | No       | suite default  |
+| seed             | int                             | Control randomness. Reuse a value for repeatability.                                                   | No       | random         |
+| cfg_scale        | float (e.g. 1–20)               | Prompt fidelity – higher = closer adherence to prompt, lower = more variety.                           | No       | 7.5           |
+| return_binary    | bool                            | Always `False`. Output is a hosted URL, not inline binary.                                             | N/A      | False         |
+| safe_mode        | bool                            | If enabled, applies content filtering / blurring for NSFW.                                             | Inherited | true         |
+| embed_exif_metadata | bool                         | If enabled, embeds prompt info in output EXIF metadata.                                                | Inherited | false         |
+| hide_watermark   | bool                            | Hide the Venice watermark, where possible.                                                            | Inherited | true           |
+
+#### Example Prompt:
+> "In the style of a Renaissance oil painting, a fierce orange tabby cat with a crown, surrounded by lush velvet drapery and golden sunlight."
+
+#### Style Presets
+An extensive list is included, for example:
+- "Photographic"
+- "Anime"
+- "Cinematic"
+- "Digital Art"
+- "Abstract"
+- "Cubist"
+- ...and over 30 more. See documentation or schema for the full list.
+
+#### Example Input:
+```json
+{
+  "prompt": "A highly detailed portrait of a robot playing chess, cinematic lighting, photoreal 4k",
+  "width": 1536,
+  "height": 1024,
+  "format": "jpeg",
+  "style_preset": "Cinematic",
+  "cfg_scale": 10,
+  "negative_prompt": "text, watermark, blurry",
+  "seed": 424242
+}
+```
+
+---
+
+## Output
+
+The tool returns a dict that includes:
+
+- `success`: true/false
+- `image_url`: The URL to the generated image (stored in S3 or similar object storage)
+- Additional metadata (generation params, seed, etc.)
+
+Example:
+```json
+{
+  "success": true,
+  "image_url": "https://s3.my-storage.net/venice_image/fluently-xl/abc123f....png",
+  "seed": 424242,
+  "generation_time_s": 22.4
+}
+```
+
+On error:
+```json
+{
+  "success": false,
+  "error": "API returned error: prompt too long",
+  "result": null
+}
+```
+
+---
+
+## Advanced Capabilities
+
+- **Inpainting**: Modify regions of an existing image with precise mask and text controls (see schema for input structure).
+- **EXIF Embedding**: If enabled, the tool can embed the prompt/config info in the output file’s EXIF metadata.
+
+---
+
+## Use Cases
+
+- **Art & Design:** Instantly create drafts, mood boards, or finished art for any assignment
+- **Marketing/Content:** Rapid visual ideation for blog posts, social media, ads, covers, etc.
+- **Ideation/Research:** Visualize concepts, inventions, or speculative scenarios quickly
+- **Education:** Generate visual teaching content on demand
+- **Character/Concept Design:** Leverage anime/artistic models for avatars, OC creation, comics
+
+---
+
+## Limitations
+
+- Results are only as good as your prompt and model choice.
+- NSFW filtering varies by model; check the tool’s description and enable `safe_mode` for safety.
+- Some style/subject combinations may not be supported by a given model.
+- Stable Diffusion/Flux Dev variants may have license restrictions—review Venice API and model TOS.
+
+---
+
+## Example Usage (Pseudo-code)
+
+```python
+result = await agent.send_tool(
+    "image_generation_fluently_xl",
+    {
+        "prompt": "A futuristic cityscape at sunset, neon lights, flying cars, cinematic",
+        "style_preset": "Cinematic",
+        "width": 1280,
+        "height": 704
+    }
+)
+url = result["image_url"]
+```
+
+---
+
+## Compliance & Attribution
+
+You must respect [Venice AI terms of service](https://venice.ai/) and the terms and licenses of the selected model.
+
+---