docs: add muapi-langchain tools integration

src/oss/python/integrations/tools/index.mdx

@@ -131,6 +131,7 @@ The following platforms provide access to multiple tools and services through a
 <Card title="Jenkins" icon="link" href="/oss/integrations/tools/jenkins" arrow="true" cta="View guide" />
 <Card title="Lemon Agent" icon="link" href="/oss/integrations/tools/lemonai" arrow="true" cta="View guide" />
 <Card title="Linkup Search Tool" icon="link" href="/oss/integrations/tools/linkup_search" arrow="true" cta="View guide" />
+<Card title="MuAPI" icon="link" href="/oss/integrations/tools/muapi" arrow="true" cta="View guide" />
 <Card title="Memgraph" icon="link" href="/oss/integrations/tools/memgraph" arrow="true" cta="View guide" />
 <Card title="Naver Search" icon="link" href="/oss/integrations/tools/naver_search" arrow="true" cta="View guide" />
 <Card title="Nia Toolkit" icon="link" href="/oss/integrations/tools/nia" arrow="true" cta="View guide" />

src/oss/python/integrations/tools/muapi.mdx

@@ -0,0 +1,222 @@
+---
+title: "muapi integration"
+description: "Use 390+ generative media models—images, video, audio, and 3D—as LangChain tools via muapi.ai."
+---
+
+[muapi.ai](https://muapi.ai) is a unified generative media API that gives agents access to 390+ models across images, video, audio, 3D, and enhancement—behind a single API key. The `muapi-langchain` package exposes these as four `@tool`-decorated functions that drop into any LangChain agent or Deep Agent.
+
+## Overview
+
+### Integration details
+
+| Tool | Package | Serializable | [JS support](https://js.langchain.com/docs/integrations/tools) | Downloads | Version |
+|:---|:---|:---:|:---:|:---:|:---:|
+| `muapi_select`, `muapi_generate`, `muapi_run_skill`, `muapi_creative_agent` | [`muapi-langchain`](https://pypi.org/project/muapi-langchain/) | ❌ | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/muapi-langchain?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/muapi-langchain?style=flat-square&label=%20) |
+
+### Tool features
+
+- **390+ models** across images (Flux, Midjourney, GPT-4o), video (Veo 3, Kling, Runway), audio (Suno), and 3D (Tripo3D, Meshy)
+- **Free model discovery**—`muapi_select` ranks candidates locally against a bundled registry, no API call
+- **Named skill recipes**—`muapi_run_skill` runs multi-step workflows (UGC ads, storyboards, product videos) in one call
+- **Budget tracking**—`MuapiCostCallback` tracks credit spend in real time and raises `BudgetExceeded` on a cap
+- **Document loader**—`MuapiAssetLoader` hydrates prior generations as LangChain `Document`s for RAG
+
+---
+
+## Setup
+
+### Credentials
+
+Create a free account at [muapi.ai](https://muapi.ai) to get an API key.
+
+```python Set API key icon="key"
+import getpass
+import os
+
+if "MUAPI_API_KEY" not in os.environ:
+    os.environ["MUAPI_API_KEY"] = getpass.getpass("Enter your muapi API key: ")
+```
+
+Optionally set up [LangSmith](/langsmith/home) for tracing:
+
+```python Enable tracing icon="flask"
+# os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
+# os.environ["LANGSMITH_TRACING"] = "true"
+```
+
+### Installation
+
+<CodeGroup>
+```python pip
+pip install -U muapi-langchain
+```
+```python uv
+uv add muapi-langchain
+```
+</CodeGroup>
+
+---
+
+## Tools
+
+The package exposes four tools that form a **capability gradient**—cheap discovery on one end, open-ended creative planning on the other:
+
+| Tool | What it does | Costs credits? |
+|------|-------------|:-:|
+| `muapi_select` | Rank models + named skills for an intent | No |
+| `muapi_generate` | Generate one asset (image / video / audio / 3D / edit) | Yes |
+| `muapi_run_skill` | Run a named multi-step recipe | Yes |
+| `muapi_creative_agent` | Hand a full brief to muapi's planning agent | Yes |
+
+```python Import tools icon="robot"
+from muapi_langchain import (
+    muapi_select,
+    muapi_generate,
+    muapi_run_skill,
+    muapi_creative_agent,
+    PLANNER_TOOLS,      # [muapi_select, muapi_generate]
+    SPECIALIST_TOOLS,   # [muapi_run_skill, muapi_creative_agent]
+    ALL_TOOLS,
+)
+```
+
+---
+
+## Invocation
+
+### Discover models (free)
+
+`muapi_select` runs locally against a bundled 390-model registry—no credits, no network call:
+
+```python Discover models icon="search"
+import json
+
+result = muapi_select.invoke({
+    "intent": "cinematic product photo of a sneaker",
+    "kind": "image",   # image | video | audio | 3d | image_edit | i2v | enhance
+    "tier": "best",    # best | balanced | fast | budget
+    "limit": 3,
+})
+
+data = json.loads(result)
+print(data["models"])   # ranked candidates
+print(data["skills"])   # matching named recipes
+```
+
+### Generate a single asset
+
+```python Generate image icon="image"
+result = muapi_generate.invoke({
+    "prompt": "A glossy white sneaker on a wet cobblestone street, neon reflections, night",
+    "kind": "image",
+    "tier": "best",
+    # model="auto" lets muapi pick based on kind + tier
+})
+
+data = json.loads(result)
+print(data["url"])       # direct URL to the generated asset
+print(data["model"])     # model that was used
+```
+
+For edits, image-to-video, lipsync, or enhancements, pass `input_asset_url`:
+
+```python Edit image icon="pencil"
+result = muapi_generate.invoke({
+    "prompt": "Remove the background",
+    "kind": "enhance",
+    "input_asset_url": "https://example.com/my-product.png",
+})
+```
+
+### Within an agent
+
+```python Agent with tools icon="robot"
+from langchain_anthropic import ChatAnthropic
+from langchain.agents import create_react_agent, AgentExecutor
+from langchain import hub
+
+llm = ChatAnthropic(model="claude-sonnet-4-6")
+prompt = hub.pull("hwchase17/react")
+
+agent = create_react_agent(llm, PLANNER_TOOLS, prompt)
+executor = AgentExecutor(agent=agent, tools=PLANNER_TOOLS, verbose=True)
+
+executor.invoke({"input": "Generate a short cinematic video of a mountain sunrise"})
+```
+
+---
+
+## Budget tracking with `MuapiCostCallback`
+
+`MuapiCostCallback` plugs into any LangChain run. It inspects each muapi tool result, accumulates credits, and raises `BudgetExceeded` if a cap is hit:
+
+```python Cost callback icon="gauge"
+from muapi_langchain import MuapiCostCallback, BudgetExceeded
+
+cost_cb = MuapiCostCallback(
+    budget_credits=300,
+    on_event=lambda evt, payload: print(evt, payload),
+)
+
+try:
+    executor.invoke(
+        {"input": "Make a 3-shot product carousel"},
+        config={"callbacks": [cost_cb]},
+    )
+except BudgetExceeded as e:
+    print(f"Budget hit: {e}")
+
+print(cost_cb.summary())
+# {'total_credits': 78, 'calls': 4, 'by_tool': {'muapi_generate': 78}, ...}
+```
+
+---
+
+## Document loader
+
+`MuapiAssetLoader` hydrates prior muapi generations as LangChain `Document`s for RAG or style-reference workflows:
+
+```python Document loader icon="file"
+from muapi_langchain import MuapiAssetLoader
+
+docs = MuapiAssetLoader(request_ids=["req_abc", "req_def"]).load()
+for d in docs:
+    print(d.metadata["url"], "·", d.page_content[:80])
+```
+
+---
+
+## Planner / specialist split (Deep Agents)
+
+For Deep Agents, split tools across a cheap planner and a heavier specialist subagent. Gate the open-ended creative agent behind `interrupt_on` for human approval:
+
+```python Deep Agent split icon="users"
+from deepagents import create_deep_agent
+from muapi_langchain import PLANNER_TOOLS, SPECIALIST_TOOLS, MuapiCostCallback
+
+agent = create_deep_agent(
+    model=llm,
+    tools=PLANNER_TOOLS,
+    subagents=[{
+        "name": "creative-specialist",
+        "description": "Runs multi-step muapi skills and open-ended creative briefs.",
+        "system_prompt": "Prefer muapi_run_skill for named recipes. Use muapi_creative_agent only for open-ended multi-asset briefs.",
+        "tools": SPECIALIST_TOOLS,
+    }],
+    interrupt_on={
+        "muapi_creative_agent": {"allowed_decisions": ["approve", "edit", "reject"]},
+    },
+)
+
+cost_cb = MuapiCostCallback(budget_credits=500)
+agent.invoke(
+    {"messages": [{"role": "user", "content": "Make a 30s product video for SunFizz mango water"}]},
+    config={"callbacks": [cost_cb]},
+)
+```
+
+---
+
+## API reference
+
+For detailed documentation of all parameters and configurations, see the [muapi-langchain source](https://github.com/SamurAIGPT/muapi-cli/tree/main/integrations/langchain) and [muapi.ai API docs](https://muapi.ai/docs).