langchain-animeapi 0.1.0__tar.gz

langchain_animeapi-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.env
+.ruff_cache/

langchain_animeapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (2026-11-12)
+
+- Initial release: `AnimeAPIGenerateImage`, a LangChain tool (sync and async) that returns the image URL, price and balance.

langchain_animeapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnimeAPI
+
+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.

langchain_animeapi-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: langchain-animeapi
+Version: 0.1.0
+Summary: AnimeAPI tool for LangChain and LangGraph agents: anime image generation at $0.003 per image.
+Project-URL: Homepage, https://animeapi.ai
+Project-URL: Documentation, https://animeapi.ai/docs
+Project-URL: Repository, https://github.com/animeapi-ai/langchain-animeapi
+Project-URL: Issues, https://github.com/animeapi-ai/langchain-animeapi/issues
+Author-email: AnimeAPI <contact@animeapi.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,anime,animeapi,image-generation,langchain,langgraph,text-to-image,tool
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: animeapi-sdk<1,>=0.1.2
+Requires-Dist: langchain-core<2,>=0.3.0
+Description-Content-Type: text/markdown
+
+# langchain-animeapi
+
+[AnimeAPI](https://animeapi.ai) tool for [LangChain](https://github.com/langchain-ai/langchain) and LangGraph agents: anime image generation at **$0.003 per image**, one of the cheapest anime image APIs. Prepaid balance from $5 that never expires, no subscription; new accounts get 3 free images without a card.
+
+```bash
+pip install langchain-animeapi
+```
+
+Create a key (it starts with `ank_`) at <https://animeapi.ai/dashboard/api-keys> and set it as `ANIMEAPI_API_KEY`.
+
+## Quick start
+
+```python
+from langchain_animeapi import AnimeAPIGenerateImage
+
+tool = AnimeAPIGenerateImage()  # reads ANIMEAPI_API_KEY
+
+print(tool.invoke({"prompt": "a shrine maiden sweeping autumn leaves", "orientation": "landscape"}))
+# Image generated: https://animeapi.ai/i/….webp
+# Model anime, landscape, $0.003. Balance left: $4.997.
+# The link is not permanent storage; download the image to keep it.
+```
+
+## With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_animeapi import AnimeAPIGenerateImage
+
+agent = create_agent(model, tools=[AnimeAPIGenerateImage()])  # model: your chat model
+result = agent.invoke({"messages": [{"role": "user", "content": "Draw a chibi cat barista, square."}]})
+```
+
+Any chat model that supports tool calling works: `model.bind_tools([AnimeAPIGenerateImage()])`. The model writes the prompt and picks the shape. When it calls the tool, the `ToolMessage` carries a short text for the model and the details as `artifact`:
+
+```python
+msg = tool.invoke({
+    "type": "tool_call", "id": "call_1", "name": "animeapi_generate_image",
+    "args": {"prompt": "a chibi cat barista holding a latte", "orientation": "square"},
+})
+msg.artifact["image_url"]        # https://animeapi.ai/i/….webp
+msg.artifact["enhanced_prompt"]  # the tags the model received
+msg.artifact["price_usd"]        # 0.003
+msg.artifact["balance_usd"]      # balance after this image
+```
+
+`ainvoke` works the same way for async agents.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `api_key` | `ANIMEAPI_API_KEY` | Your key. Stored as a secret, so it does not show up in `repr()` or traces. |
+| `model` | `"anime"` | `"anime"` $0.003, `"ultra"` $0.01, `"ultra-max"` $0.02 per image. Set by you, not by the language model, so an agent cannot pick a more expensive one. |
+| `enhance` | `True` | Rewrites plain words into tags for the anime model. |
+| `timeout` | `120` | Seconds to wait for one request. |
+| `max_retries` | `2` | Retries for failures the API marks as retryable. |
+
+What the language model can set per call: `prompt` (up to 1000 characters) and `orientation` (`portrait`, `square` or `landscape`; same price).
+
+AnimeAPI does not generate adult content. Explicit prompts are refused and not charged.
+
+## Errors
+
+A failed call does not raise inside your agent: the tool answers with an error `ToolMessage` carrying AnimeAPI's own message, so the model can tell the user what happened (prompt refused, wrong key, empty balance). Set `handle_tool_error=False` to get a `ToolException` instead.
+
+## Keeping the image
+
+Image URLs are not permanent storage. Download what you want to keep, for example with the SDK this package is built on:
+
+```python
+from animeapi import AnimeAPI
+
+AnimeAPI().download(msg.artifact["image_url"]).save("cat.webp")
+```
+
+## Prices
+
+| Model | Price per image | Use it for |
+| --- | --- | --- |
+| `anime` | **$0.003** | Characters, portraits, avatars, scenes. About 4 seconds. |
+| `ultra` | $0.01 | Long, detailed prompts; legible text in the image. |
+| `ultra-max` | $0.02 | Highest detail. |
+
+## Tested
+
+Run against the live API with `langchain-core` 1.8.0 on 2026-11-12: a direct call, a tool call (returns a `ToolMessage` with the artifact), an async tool call, a refused prompt and a wrong key (both come back as error messages, uncharged).
+
+## Links
+
+- AnimeAPI: <https://animeapi.ai> · [Docs](https://animeapi.ai/docs) · [API reference](https://animeapi.ai/docs/api-reference)
+- Python SDK: [animeapi-sdk](https://github.com/animeapi-ai/animeapi-python) · MCP server for agents: <https://animeapi.ai/mcp>
+- Licence: [MIT](LICENSE)

langchain_animeapi-0.1.0/README.md

@@ -0,0 +1,93 @@
+# langchain-animeapi
+
+[AnimeAPI](https://animeapi.ai) tool for [LangChain](https://github.com/langchain-ai/langchain) and LangGraph agents: anime image generation at **$0.003 per image**, one of the cheapest anime image APIs. Prepaid balance from $5 that never expires, no subscription; new accounts get 3 free images without a card.
+
+```bash
+pip install langchain-animeapi
+```
+
+Create a key (it starts with `ank_`) at <https://animeapi.ai/dashboard/api-keys> and set it as `ANIMEAPI_API_KEY`.
+
+## Quick start
+
+```python
+from langchain_animeapi import AnimeAPIGenerateImage
+
+tool = AnimeAPIGenerateImage()  # reads ANIMEAPI_API_KEY
+
+print(tool.invoke({"prompt": "a shrine maiden sweeping autumn leaves", "orientation": "landscape"}))
+# Image generated: https://animeapi.ai/i/….webp
+# Model anime, landscape, $0.003. Balance left: $4.997.
+# The link is not permanent storage; download the image to keep it.
+```
+
+## With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_animeapi import AnimeAPIGenerateImage
+
+agent = create_agent(model, tools=[AnimeAPIGenerateImage()])  # model: your chat model
+result = agent.invoke({"messages": [{"role": "user", "content": "Draw a chibi cat barista, square."}]})
+```
+
+Any chat model that supports tool calling works: `model.bind_tools([AnimeAPIGenerateImage()])`. The model writes the prompt and picks the shape. When it calls the tool, the `ToolMessage` carries a short text for the model and the details as `artifact`:
+
+```python
+msg = tool.invoke({
+    "type": "tool_call", "id": "call_1", "name": "animeapi_generate_image",
+    "args": {"prompt": "a chibi cat barista holding a latte", "orientation": "square"},
+})
+msg.artifact["image_url"]        # https://animeapi.ai/i/….webp
+msg.artifact["enhanced_prompt"]  # the tags the model received
+msg.artifact["price_usd"]        # 0.003
+msg.artifact["balance_usd"]      # balance after this image
+```
+
+`ainvoke` works the same way for async agents.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `api_key` | `ANIMEAPI_API_KEY` | Your key. Stored as a secret, so it does not show up in `repr()` or traces. |
+| `model` | `"anime"` | `"anime"` $0.003, `"ultra"` $0.01, `"ultra-max"` $0.02 per image. Set by you, not by the language model, so an agent cannot pick a more expensive one. |
+| `enhance` | `True` | Rewrites plain words into tags for the anime model. |
+| `timeout` | `120` | Seconds to wait for one request. |
+| `max_retries` | `2` | Retries for failures the API marks as retryable. |
+
+What the language model can set per call: `prompt` (up to 1000 characters) and `orientation` (`portrait`, `square` or `landscape`; same price).
+
+AnimeAPI does not generate adult content. Explicit prompts are refused and not charged.
+
+## Errors
+
+A failed call does not raise inside your agent: the tool answers with an error `ToolMessage` carrying AnimeAPI's own message, so the model can tell the user what happened (prompt refused, wrong key, empty balance). Set `handle_tool_error=False` to get a `ToolException` instead.
+
+## Keeping the image
+
+Image URLs are not permanent storage. Download what you want to keep, for example with the SDK this package is built on:
+
+```python
+from animeapi import AnimeAPI
+
+AnimeAPI().download(msg.artifact["image_url"]).save("cat.webp")
+```
+
+## Prices
+
+| Model | Price per image | Use it for |
+| --- | --- | --- |
+| `anime` | **$0.003** | Characters, portraits, avatars, scenes. About 4 seconds. |
+| `ultra` | $0.01 | Long, detailed prompts; legible text in the image. |
+| `ultra-max` | $0.02 | Highest detail. |
+
+## Tested
+
+Run against the live API with `langchain-core` 1.8.0 on 2026-11-12: a direct call, a tool call (returns a `ToolMessage` with the artifact), an async tool call, a refused prompt and a wrong key (both come back as error messages, uncharged).
+
+## Links
+
+- AnimeAPI: <https://animeapi.ai> · [Docs](https://animeapi.ai/docs) · [API reference](https://animeapi.ai/docs/api-reference)
+- Python SDK: [animeapi-sdk](https://github.com/animeapi-ai/animeapi-python) · MCP server for agents: <https://animeapi.ai/mcp>
+- Licence: [MIT](LICENSE)

langchain_animeapi-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-animeapi"
+dynamic = ["version"]
+description = "AnimeAPI tool for LangChain and LangGraph agents: anime image generation at $0.003 per image."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "AnimeAPI", email = "contact@animeapi.ai" }]
+keywords = ["langchain", "langgraph", "tool", "agent", "anime", "image-generation", "text-to-image", "animeapi", "ai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = ["langchain-core>=0.3.0,<2", "animeapi-sdk>=0.1.2,<1"]
+
+[project.urls]
+Homepage = "https://animeapi.ai"
+Documentation = "https://animeapi.ai/docs"
+Repository = "https://github.com/animeapi-ai/langchain-animeapi"
+Issues = "https://github.com/animeapi-ai/langchain-animeapi/issues"
+
+[tool.hatch.version]
+path = "src/langchain_animeapi/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_animeapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]

langchain_animeapi-0.1.0/src/langchain_animeapi/__init__.py

@@ -0,0 +1,14 @@
+"""AnimeAPI tool for LangChain and LangGraph agents (https://animeapi.ai).
+
+Anime image generation at $0.003 per image.
+
+    from langchain_animeapi import AnimeAPIGenerateImage
+
+    tool = AnimeAPIGenerateImage()  # reads ANIMEAPI_API_KEY
+    print(tool.invoke({"prompt": "a silver-haired girl reading under a cherry tree"}))
+"""
+
+from ._version import __version__
+from .tools import AnimeAPIGenerateImage, AnimeAPIGenerateImageInput
+
+__all__ = ["AnimeAPIGenerateImage", "AnimeAPIGenerateImageInput", "__version__"]

langchain_animeapi-0.1.0/src/langchain_animeapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

langchain_animeapi-0.1.0/src/langchain_animeapi/tools.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Literal, Optional, Tuple, Type
+
+from animeapi import AnimeAPI, AnimeAPIError, AsyncAnimeAPI
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool, ToolException
+from pydantic import BaseModel, Field, SecretStr
+
+PRICES_USD = {"anime": 0.003, "ultra": 0.01, "ultra-max": 0.02}
+
+
+class AnimeAPIGenerateImageInput(BaseModel):
+    """What the model fills in when it calls the tool."""
+
+    prompt: str = Field(
+        description=(
+            "What to draw: subject, appearance, pose, setting, lighting. "
+            "Plain English works best. At most 1000 characters."
+        ),
+        max_length=1000,
+    )
+    orientation: Literal["portrait", "square", "landscape"] = Field(
+        default="portrait",
+        description=(
+            "Shape of the image: portrait (characters, full body), square (avatars, icons) "
+            "or landscape (scenery, wide scenes). Same price for every shape."
+        ),
+    )
+
+
+class AnimeAPIGenerateImage(BaseTool):
+    """Generate an anime image with AnimeAPI: $0.003 per image on the default model.
+
+    Setup:
+        ``pip install langchain-animeapi`` and set ``ANIMEAPI_API_KEY`` (keys start with
+        ``ank_``; create one at https://animeapi.ai/dashboard/api-keys).
+
+    The model chooses the prompt and the shape. You choose the image model here, so an
+    agent cannot switch to a more expensive one:
+
+        tool = AnimeAPIGenerateImage(model="anime")   # $0.003 per image (default)
+        tool = AnimeAPIGenerateImage(model="ultra")   # $0.01 per image
+
+    The tool returns a short text for the model (the image URL, price and balance left)
+    and, as the artifact, a dict with ``image_url``, ``enhanced_prompt``, ``model``,
+    ``orientation``, ``price_usd``, ``balance_usd`` and ``generation_time_ms``.
+    """
+
+    name: str = "animeapi_generate_image"
+    description: str = (
+        "Generate one anime-style image from a text description and return its URL. "
+        "Costs $0.003 per image on the default model. Describe the subject, appearance, pose, "
+        "setting and lighting in plain English. "
+        "Adult content is not available; explicit prompts are refused and not charged."
+    )
+    args_schema: Type[BaseModel] = AnimeAPIGenerateImageInput
+    response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
+    handle_tool_error: bool = True
+
+    api_key: Optional[SecretStr] = Field(default=None, description="Defaults to ANIMEAPI_API_KEY.")
+    model: Literal["anime", "ultra", "ultra-max"] = "anime"
+    enhance: bool = True
+    timeout: float = 120.0
+    max_retries: int = 2
+
+    def _client_kwargs(self) -> Dict[str, Any]:
+        return {
+            "api_key": self.api_key.get_secret_value() if self.api_key else None,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+        }
+
+    def _result(self, image: Any, orientation: str) -> Tuple[str, Dict[str, Any]]:
+        price = PRICES_USD[self.model]
+        content = (
+            f"Image generated: {image.image_url}\n"
+            f"Model {self.model}, {orientation}, ${price}. Balance left: ${image.balance_usd}.\n"
+            "The link is not permanent storage; download the image to keep it."
+        )
+        artifact = {
+            "image_url": image.image_url,
+            "enhanced_prompt": image.enhanced_prompt,
+            "model": self.model,
+            "orientation": orientation,
+            "price_usd": price,
+            "balance_usd": image.balance_usd,
+            "generation_time_ms": image.generation_time_ms,
+        }
+        return content, artifact
+
+    @staticmethod
+    def _tool_error(e: AnimeAPIError) -> ToolException:
+        # The API's own message, e.g. why a prompt was refused or that the balance is empty.
+        return ToolException(f"AnimeAPI: {e.message} ({e.code or e.status})")
+
+    def _run(
+        self,
+        prompt: str,
+        orientation: str = "portrait",
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> Tuple[str, Dict[str, Any]]:
+        try:
+            with AnimeAPI(**self._client_kwargs()) as client:
+                image = client.images.generate(
+                    prompt, model=self.model, orientation=orientation, enhance=self.enhance  # type: ignore[arg-type]
+                )
+        except AnimeAPIError as e:
+            raise self._tool_error(e) from e
+        return self._result(image, orientation)
+
+    async def _arun(
+        self,
+        prompt: str,
+        orientation: str = "portrait",
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> Tuple[str, Dict[str, Any]]:
+        try:
+            async with AsyncAnimeAPI(**self._client_kwargs()) as client:
+                image = await client.images.generate(
+                    prompt, model=self.model, orientation=orientation, enhance=self.enhance  # type: ignore[arg-type]
+                )
+        except AnimeAPIError as e:
+            raise self._tool_error(e) from e
+        return self._result(image, orientation)