idiotproof 0.5.0__py3-none-any.whl

idiotproof/__init__.py

@@ -0,0 +1,38 @@
+"""The small public surface of the IDEA Agent Development Kit."""
+
+from .media import (
+    CombinedMedia,
+    DownloadedMedia,
+    MediaConcatIncompatible,
+    MediaDimensionMismatch,
+    MediaDimensions,
+    download_and_concat,
+)
+from .sdk import (
+    BoundRuntimeTool,
+    ChatId,
+    Idea,
+    IdeaBatchError,
+    IdeaError,
+    MapItem,
+    RuntimeTool,
+    numbered_media,
+)
+
+__all__ = [
+    "BoundRuntimeTool",
+    "ChatId",
+    "CombinedMedia",
+    "DownloadedMedia",
+    "Idea",
+    "IdeaBatchError",
+    "IdeaError",
+    "MapItem",
+    "MediaConcatIncompatible",
+    "MediaDimensionMismatch",
+    "MediaDimensions",
+    "RuntimeTool",
+    "download_and_concat",
+    "numbered_media",
+]
+__version__ = "0.5.0"

idiotproof/cli.py

@@ -0,0 +1,146 @@
+"""Command-line and stdio MCP entry point for IDEA ADK."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from .sdk import Idea, IdeaError, MapItem
+
+
+def _json_input(value: str) -> dict[str, Any]:
+    text = Path(value[1:]).read_text() if value.startswith("@") else value
+    parsed = json.loads(text)
+    if not isinstance(parsed, dict):
+        raise ValueError("tool input must be a JSON object")
+    return parsed
+
+
+def _map_item_json(item: MapItem) -> dict[str, Any]:
+    if item.error is None:
+        return {"index": item.index, "result": item.result}
+    return {
+        "index": item.index,
+        "error": {
+            "message": str(item.error),
+            "code": item.error.code,
+            "status_code": item.error.status_code,
+            "details": item.error.details,
+            "request_id": item.error.request_id,
+        },
+    }
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="idea-adk",
+        description="Software for agents that create and edit video.",
+    )
+    parser.add_argument("--base-url", help="override IDEA_API_BASE_URL")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    commands.add_parser("create-chat", help="create a new opaque chatId")
+
+    upload = commands.add_parser("upload-file", help="upload and normalize media")
+    upload.add_argument("chat_id")
+    upload.add_argument("path")
+
+    commands.add_parser("get-tools", help="print the live MCP catalog")
+
+    call = commands.add_parser("call", help="call one live tool by exact name")
+    call.add_argument("chat_id")
+    call.add_argument("tool")
+    call.add_argument("--input", default="{}", help="JSON object or @path/to/input.json")
+
+    mapped = commands.add_parser("map", help="call one live tool over many inputs")
+    mapped.add_argument("chat_id")
+    mapped.add_argument("tool")
+    mapped.add_argument("--input", required=True, help="batch JSON object or @path")
+    mapped.add_argument("--concurrency", type=int, default=4)
+    mapped.add_argument("--errors", choices=("raise", "collect"), default="raise")
+
+    publish = commands.add_parser("media-publish", help="publish a workspace media file")
+    publish.add_argument("chat_id")
+    publish.add_argument("media_path")
+    publish.add_argument("--ttl-seconds", type=int, default=7200)
+
+    commands.add_parser("mcp", help="run the stdio MCP server")
+    return parser
+
+
+async def _execute(args: argparse.Namespace) -> Any:
+    if args.command == "mcp":
+        from .mcp_server import serve
+
+        await serve(base_url=args.base_url)
+        return None
+
+    async with Idea(base_url=args.base_url) as idea:
+        if args.command == "create-chat":
+            return {"chatId": await idea.create_chat()}
+        if args.command == "upload-file":
+            return await idea.upload_file(args.chat_id, args.path)
+        if args.command == "get-tools":
+            tools = await idea.get_tools()
+            return {"tools": list(tools.catalog)}
+        if args.command == "call":
+            tools = await idea.get_tools()
+            return await tools.call(args.tool, args.chat_id, _json_input(args.input))
+        if args.command == "map":
+            batch = _json_input(args.input)
+            inputs = batch.get("inputs")
+            common = batch.get("common")
+            if not isinstance(inputs, list):
+                raise ValueError("map input must contain an inputs array")
+            if common is not None and not isinstance(common, dict):
+                raise ValueError("map common must be an object")
+            tools = await idea.get_tools()
+            results = await tools.map(
+                args.tool,
+                args.chat_id,
+                inputs,
+                common=common,
+                concurrency=args.concurrency,
+                errors=args.errors,
+            )
+            if args.errors == "collect":
+                items = cast(list[MapItem], results)
+                return {"items": [_map_item_json(item) for item in items]}
+            return {"results": results}
+        if args.command == "media-publish":
+            return await idea.media_publish(
+                args.chat_id,
+                args.media_path,
+                ttl_seconds=args.ttl_seconds,
+            )
+    raise AssertionError(f"unhandled command: {args.command}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Run the command-line interface."""
+
+    args = _parser().parse_args(argv)
+    try:
+        result = asyncio.run(_execute(args))
+    except (IdeaError, OSError, TypeError, ValueError, json.JSONDecodeError) as error:
+        payload: dict[str, Any] = {"error": {"message": str(error)}}
+        if isinstance(error, IdeaError):
+            payload["error"].update(
+                {
+                    "code": error.code,
+                    "status_code": error.status_code,
+                    "request_id": error.request_id,
+                }
+            )
+        print(json.dumps(payload), file=sys.stderr)
+        raise SystemExit(1) from error
+    if result is not None:
+        print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

idiotproof/mcp_server.py

@@ -0,0 +1,216 @@
+"""A dependency-free stdio MCP adapter over :mod:`idiotproof`."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from collections.abc import Mapping
+from typing import Any
+
+from .sdk import Idea, IdeaError, Json, _tool_attribute
+
+_LATEST_PROTOCOL = "2025-11-25"
+_SUPPORTED_PROTOCOLS = {"2024-11-05", "2025-03-26", "2025-06-18", _LATEST_PROTOCOL}
+_INSTRUCTIONS = """This ADK is software for agents, intended for one-off scripts and tool calls—not
+as a stable dependency for persistent applications. Use one create_chat result for an entire
+workspace. Uploads are normalized to 600 frames at 3 megapixels; upload_file automatically splits a
+longer video into ordered, reserved <=600-frame parts. Assign batch, asset, and part sequence
+metadata before concurrent uploads; completion order is never media order. For novel effects, map
+variants over one representative preview capped near 590 frames before rendering every segment.
+Use FFmpeg for cuts, joins, codecs, and audio. Use discovered
+VLM/frame tools to inspect video and return grounding coordinates in [0,1000). Use Bobbie for GLSL,
+ML, and CUDA vision pipelines; bindings are assigned automatically. Independent tool calls may run
+in parallel. After
+discovering tools in Python, use partial() to bind shared arguments and map() for ordered, bounded
+concurrency over varying inputs. Map does not retry tool calls, and remote work already accepted
+may continue after local cancellation. After media_publish, transiently embed the signed URL in
+HTML generated by an in-memory viewer, serve it only on 127.0.0.1, and open or provide the localhost
+URL. Do not download merely to preview. Do not print the signed URL or write it to HTML, manifests,
+or logs; stop the viewer after review.
+For durable output, use download_media or ordered download_and_concat; both keep signed URLs out of
+resume state and replace final paths only after verification. Save important media because
+workspaces are deleted aggressively."""
+
+_FIXED_TOOLS: list[Json] = [
+    {
+        "name": "create_chat",
+        "description": (
+            "Create an opaque chatId. Reuse it for every upload and tool call in one workspace."
+        ),
+        "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False},
+    },
+    {
+        "name": "upload_file",
+        "description": "Upload and normalize one local image or video into an IDEA workspace.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "chatId": {"type": "string", "description": "ID returned by create_chat."},
+                "path": {"type": "string", "description": "Local media file path."},
+            },
+            "required": ["chatId", "path"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "get_tools",
+        "description": "Return the server's current MCP tool descriptions and JSON Schemas.",
+        "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False},
+    },
+]
+
+
+def _dynamic_definition(item: Mapping[str, Any]) -> Json | None:
+    tool_id = item.get("id")
+    if not isinstance(tool_id, str) or not tool_id:
+        return None
+    schema_value = item.get("input_schema")
+    schema: Json = dict(schema_value) if isinstance(schema_value, Mapping) else {"type": "object"}
+    properties_value = schema.get("properties")
+    properties = dict(properties_value) if isinstance(properties_value, Mapping) else {}
+    properties = {
+        "chatId": {
+            "type": "string",
+            "description": "The workspace chatId returned by create_chat.",
+        },
+        **properties,
+    }
+    required_value = schema.get("required")
+    required = list(required_value) if isinstance(required_value, list) else []
+    if "chatId" not in required:
+        required.insert(0, "chatId")
+    schema.update({"type": "object", "properties": properties, "required": required})
+    return {
+        "name": _tool_attribute(tool_id),
+        "description": str(item.get("description") or ""),
+        "inputSchema": schema,
+        "_idea_tool_id": tool_id,
+    }
+
+
+class _Server:
+    def __init__(self, idea: Idea) -> None:
+        self.idea = idea
+        self.dynamic: dict[str, str] = {}
+
+    async def tools(self) -> list[Json]:
+        result = [dict(item) for item in _FIXED_TOOLS]
+        fixed_names = {str(item["name"]) for item in result}
+        try:
+            catalog = await self.idea.get_tools(refresh=True)
+        except IdeaError:
+            return result
+        dynamic: dict[str, str] = {}
+        for item in catalog:
+            definition = _dynamic_definition(item)
+            if definition is None:
+                continue
+            name = str(definition["name"])
+            if name in fixed_names or name in dynamic:
+                continue
+            dynamic[name] = str(definition.pop("_idea_tool_id"))
+            result.append(definition)
+        self.dynamic = dynamic
+        return result
+
+    async def call(self, name: str, arguments: Mapping[str, Any]) -> Json:
+        values = dict(arguments)
+        if name == "create_chat":
+            return {"chatId": await self.idea.create_chat()}
+        if name == "get_tools":
+            tools = await self.idea.get_tools(refresh=True)
+            return {"tools": list(tools.catalog)}
+        if name == "upload_file":
+            chat_id = values.pop("chatId")
+            path = values.pop("path")
+            if values:
+                raise IdeaError("upload_file received unknown arguments", code="invalid_tool_input")
+            return await self.idea.upload_file(str(chat_id), str(path))
+        if not self.dynamic:
+            await self.tools()
+        tool_id = self.dynamic.get(name)
+        if tool_id is None:
+            raise IdeaError(f"unknown tool: {name}", code="unknown_tool")
+        try:
+            chat_id = values.pop("chatId")
+        except KeyError as error:
+            raise IdeaError("chatId is required", code="invalid_tool_input") from error
+        tools = await self.idea.get_tools()
+        return await tools.call(tool_id, str(chat_id), values)
+
+    async def dispatch(self, request: Mapping[str, Any]) -> Json | None:
+        request_id = request.get("id")
+        method = request.get("method")
+        if request_id is None:
+            return None
+        try:
+            if method == "initialize":
+                params = request.get("params")
+                requested = params.get("protocolVersion") if isinstance(params, Mapping) else None
+                result: Any = {
+                    "protocolVersion": (
+                        requested if requested in _SUPPORTED_PROTOCOLS else _LATEST_PROTOCOL
+                    ),
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "idea-adk", "version": "0.5.0"},
+                    "instructions": _INSTRUCTIONS,
+                }
+            elif method == "ping":
+                result = {}
+            elif method == "tools/list":
+                result = {"tools": await self.tools()}
+            elif method == "tools/call":
+                params = request.get("params")
+                if not isinstance(params, Mapping) or not isinstance(params.get("name"), str):
+                    raise IdeaError("tools/call requires a name", code="invalid_tool_input")
+                args = params.get("arguments", {})
+                if not isinstance(args, Mapping):
+                    raise IdeaError("tool arguments must be an object", code="invalid_tool_input")
+                try:
+                    output = await self.call(str(params["name"]), args)
+                    result = {
+                        "content": [{"type": "text", "text": json.dumps(output)}],
+                        "structuredContent": output,
+                        "isError": False,
+                    }
+                except (IdeaError, KeyError, TypeError, ValueError) as error:
+                    result = {
+                        "content": [{"type": "text", "text": str(error)}],
+                        "isError": True,
+                    }
+            else:
+                return {
+                    "jsonrpc": "2.0",
+                    "id": request_id,
+                    "error": {"code": -32601, "message": f"method not found: {method}"},
+                }
+            return {"jsonrpc": "2.0", "id": request_id, "result": result}
+        except Exception as error:
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "error": {"code": -32603, "message": str(error)},
+            }
+
+
+async def serve(*, base_url: str | None = None) -> None:
+    """Serve newline-delimited MCP JSON-RPC over stdin/stdout."""
+
+    async with Idea(base_url=base_url) as idea:
+        server = _Server(idea)
+        while line := await asyncio.to_thread(sys.stdin.buffer.readline):
+            try:
+                request = json.loads(line)
+                if not isinstance(request, dict):
+                    raise ValueError("request must be an object")
+                response = await server.dispatch(request)
+            except (json.JSONDecodeError, ValueError) as error:
+                response = {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": -32700, "message": str(error)},
+                }
+            if response is not None:
+                sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
+                sys.stdout.flush()