belgie 0.38.0

Generative AI/UI sandbox for Python

Belgie: Generative AI/UI Sandbox for Python

Belgie is a sandboxed TypeScript environment for Python that lets you build React MCP Apps and have agents write code in a sandbox.

• MCP Apps: Attach React widgets to Python MCP tools in one project.
• AI agents: Sandboxed run_code so Pydantic AI and LangChain can run TypeScript and TSX.
• Inline React widgets: Return self-contained HTML from run_code with @belgie/render.
• Sandbox: Deno is bundled, so you do not need to install Node.js.

Installation

uv add belgie
uvx library-skills install  # optional: install the use-belgie skill for Cursor, Codex, Claude, etc.

For MCP Apps, install the MCP and CLI extras:

uv add "belgie[mcp,cli]"

MCP Apps

Skip the second package manager. Attach a React widget to a Python MCP tool. BelgieExtension starts Vite in the background for development and runs a one-time production build.

from datetime import UTC, datetime
from pathlib import Path

from mcp.server import MCPServer

from belgie.mcp import BelgieExtension

belgie = BelgieExtension(project=".")


@belgie.tool(
    widget=Path("src/widgets/get-time/widget.tsx"),
    name="get-time",
    title="Get Time",
    description="Get the current server time in ISO 8601 format.",
)
def get_time() -> dict[str, str]:
    return {"time": datetime.now(tz=UTC).isoformat()}


mcp = MCPServer(name="Get Time Server", extensions=[belgie])

The widget is a normal React entry. @belgie/mcp connects the MCP Apps host and surfaces the opening tool result:

import { Widget, useToolResult } from "@belgie/mcp";
import { getTime } from "@widgets/tools";

function AppView() {
  const { data, isLoading, execute } = useToolResult(getTime);
  return (
    <main>
      <p>{data?.time ?? (isLoading ? "Waiting..." : "No time returned.")}</p>
      <button onClick={() => void execute()}>Refresh</button>
    </main>
  );
}

export default function GetTime() {
  return (
    <Widget metadata={{ name: "Get Time", version: "1.0.0" }}>
      <AppView />
    </Widget>
  );
}

Declare JS deps under [tool.belgie.dependencies], then:

uv run belgie lock
uv run belgie install
# start your MCP server; Belgie starts Vite with widget HMR

Pass build=False to BelgieExtension when Vite is managed separately or production assets are already built.

Runnable projects:

• mcp: Minimal MCP Apps widget.
• shadcn: Same pattern with Tailwind CSS and shadcn/ui.
• tanstack: TanStack Start SPA and MCP widget served together through FastAPI.

AI agents

When an agent needs an npm package, a browser-style API, or a JS-side transform, give it run_code. Belgie executes the TypeScript, JavaScript, or TSX in the embedded Deno sandbox. No separate Node install.

Pydantic AI

Install with uv add "belgie[pydantic-ai]", set OPENAI_API_KEY, then:

from pydantic_ai import Agent

from belgie.pydantic_ai import BelgieCapability

agent = Agent("openai:gpt-5", capabilities=[BelgieCapability()])

result = agent.run_sync(
    "Convert 'foo-bar' to camelCase using TypeScript and the camelcase npm package.",
)
print(result.output)

See examples/ai/pydantic-ai.

LangChain

Install with uv add "belgie[langchain]", set OPENAI_API_KEY, then:

from langchain.agents import create_agent

from belgie.langchain import BelgieMiddleware

agent = create_agent(
    model="openai:gpt-5",
    tools=[],
    middleware=[BelgieMiddleware()],
    system_prompt="You can execute JS/TS in a Deno sandbox with run_code.",
)

result = agent.invoke(
    {
        "messages": [
            (
                "user",
                "Convert 'foo-bar' to camelCase using TypeScript and the camelcase npm package.",
            ),
        ],
    },
)
print(result["messages"][-1].content)

See examples/ai/langchain.

Under the hood: Deno in Python

MCP Apps and agent run_code both use Belgie’s embedded Deno runtime. Call it directly when you need JS/TS from Python without MCP or an agent framework:

• Scripts: Inline or file-based JS/TS with Runtime and Script, sync or async.
• Inline dependencies: Import npm, JSR, and URL modules from source.
• Environments: Lockfiles, custom cache/options, local packages, and Command for npm binaries (Vite, esbuild, etc.).
• Data bridge: Pass JSON-safe dicts, lists, and primitives across the boundary.

import asyncio

from belgie import Runtime, Script

script = Script[[str], str](
    """
import camelcase from "npm:camelcase@8.0.0";

export default function run(input: string): string {
  return camelcase(input);
}
"""
)


async def main() -> None:
    async with Runtime() as run:
        print(await run(script)("foo-bar"))  # prints: fooBar


asyncio.run(main())

Inline widget rendering

Pydantic AI and LangChain agents can return a complete inline React widget through the same run_code tool. The agent writes one TSX module and imports the standalone renderer:

import { render } from "npm:@belgie/render";

function Widget() {
  return <main>Hello from Belgie</main>;
}

export default function run() {
  return render({
    widget: <Widget />,
    plugins: [],
  });
}

render() requests HTML from a Belgie-owned renderer side-channel (not from the model-visible Deno worker). The agent Script stays workspace-restricted — no host /etc//proc, allow_sys, or allow_ffi — while Vite runs only in that host-mediated worker (workspace FFI/sys/write, no host path grants) and returns one self-contained HTML string with inline JavaScript, CSS, and assets. Package imports are supported. Relative host-file imports are intentionally unavailable, and Vite plugins run only during the server build before their expressions and plugin-only imports are removed from the browser bundle. This API is independent from @belgie/mcp and its path-based widget.tsx development and production flow.

Examples

Small, runnable projects. Each focuses on one capability.

UI

• mcp: MCP Apps extension with a React widget built through Belgie.
• shadcn: MCP Apps widget styled with Tailwind CSS and shadcn/ui.
• tanstack: TanStack Start SPA and MCP widget served together through FastAPI.

AI

• pydantic-ai: Pydantic AI agent with BelgieCapability() for sandboxed JS/TS/TSX execution.
• langchain: LangChain agent with BelgieMiddleware() for sandboxed JS/TS/TSX execution.

Basic

• simple: Async Runtime with a TypeScript file on disk.
• inline-deps: Direct npm:, jsr:, and URL imports in a script.
• jsr-deps: JSR packages declared through an explicit Environment.
• pyproject: Manage project package dependencies with belgie[cli] and [tool.belgie.dependencies].
• environment: Sync and async Environment setup with path.
• commands: npm package binaries via Runtime and Command.

For deeper integration guidance, optionally install the use-belgie skill with uvx library-skills install.