bowerbot 1.5.0__py3-none-any.whl

bowerbot/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 Binary Core LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""BowerBot — AI-powered 3D scene assembly using OpenUSD."""
+
+from importlib.metadata import version
+
+__version__ = version("bowerbot")

bowerbot/agent.py

@@ -0,0 +1,185 @@
+# Copyright 2026 Binary Core LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""AgentRuntime — the 'Architect' layer.
+
+Runs a tool-calling loop against an LLM: the model decides what to
+call, the dispatcher executes it against the shared
+:class:`~bowerbot.state.SceneState`, results feed back into the
+conversation, and the loop repeats until the model returns prose.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import litellm
+
+from bowerbot import dispatcher
+from bowerbot.config import Settings
+from bowerbot.prompts import load_prompt
+from bowerbot.skills.base import ToolResult
+from bowerbot.skills.registry import SkillRegistry
+from bowerbot.state import SceneState
+from bowerbot.token_manager import TokenManager
+
+logger = logging.getLogger(__name__)
+
+MAX_VALIDATION_RETRIES = 2
+
+
+@dataclass
+class AgentRuntime:
+    """LLM tool-calling loop bound to a single :class:`SceneState`."""
+
+    settings: Settings
+    state: SceneState
+    skill_registry: SkillRegistry
+    conversation_history: list[dict[str, Any]] = field(default_factory=list)
+    _system_prompt: str = field(default="", init=False)
+    _tools: list[dict[str, Any]] = field(default_factory=list, init=False)
+    _token_manager: TokenManager = field(init=False)
+    _scene_tool_names: set[str] = field(default_factory=set, init=False)
+
+    def __post_init__(self) -> None:
+        """Assemble the system prompt and cache the tool list."""
+        self._system_prompt = self._build_system_prompt()
+        self._tools = (
+            dispatcher.get_tool_schemas()
+            + self.skill_registry.get_all_tools()
+        )
+        self._token_manager = TokenManager(self.settings.llm)
+        self._scene_tool_names = dispatcher.get_tool_names()
+
+        logger.info(
+            "System prompt: %d chars, %d scene tools + %d skill(s)",
+            len(self._system_prompt),
+            len(dispatcher.TOOLS),
+            self.skill_registry.skill_count,
+        )
+
+    def _build_system_prompt(self) -> str:
+        """Stitch together core + scene-building + skill prompt sections."""
+        sections = [
+            load_prompt("core"),
+            f"# Scene Building\n\n{load_prompt('scene_building')}",
+            f"# Asset Library\n\n{load_prompt('library')}",
+            f"# Textures\n\n{load_prompt('textures')}",
+        ]
+        skill_prompts = self.skill_registry.get_skill_prompts()
+        if skill_prompts:
+            sections.append(f"# Extension Skills\n\n{skill_prompts}")
+        return "\n\n---\n\n".join(sections)
+
+    async def process(self, user_message: str) -> str:
+        """Run the tool-calling loop until the LLM returns prose."""
+        self.conversation_history.append(
+            {"role": "user", "content": user_message},
+        )
+        validation_retries = 0
+
+        for round_num in range(self.settings.llm.max_tool_rounds):
+            logger.info("Agent loop round %s", round_num + 1)
+
+            messages, _ = await self._token_manager.prepare_messages(
+                self._system_prompt, self.conversation_history,
+            )
+
+            kwargs: dict[str, Any] = {
+                "model": self.settings.llm.model,
+                "messages": messages,
+                "max_tokens": self.settings.llm.max_tokens,
+                "temperature": self.settings.llm.temperature,
+                "num_retries": self.settings.llm.num_retries,
+                "timeout": self.settings.llm.request_timeout,
+            }
+            api_key = self.settings.get_api_key()
+            if api_key:
+                kwargs["api_key"] = api_key
+            if self._tools:
+                kwargs["tools"] = self._tools
+
+            response = await litellm.acompletion(**kwargs)
+            message = response.choices[0].message
+
+            if not message.tool_calls:
+                content = message.content or ""
+                self.conversation_history.append(
+                    {"role": "assistant", "content": content},
+                )
+                return content
+
+            logger.info("LLM requested %s tool call(s)", len(message.tool_calls))
+            self.conversation_history.append(message.model_dump())
+
+            for tool_call in message.tool_calls:
+                await self._run_tool_call(tool_call)
+
+            if self._nudge_on_validation_errors(
+                message.tool_calls, validation_retries,
+            ):
+                validation_retries += 1
+
+        return "Reached maximum tool-calling rounds. Please try a simpler request."
+
+    async def _run_tool_call(self, tool_call: Any) -> None:
+        """Execute a single tool call and append its result to history."""
+        func_name = tool_call.function.name
+        func_args = json.loads(tool_call.function.arguments)
+        logger.info("Executing tool: %s(%s)", func_name, func_args)
+
+        result = await self._dispatch_tool(func_name, func_args)
+        self.conversation_history.append({
+            "role": "tool",
+            "tool_call_id": tool_call.id,
+            "content": json.dumps(
+                result.data if result.success else {"error": result.error},
+            ),
+        })
+
+    async def _dispatch_tool(
+        self, func_name: str, func_args: dict[str, Any],
+    ) -> ToolResult:
+        """Route a tool call to the dispatcher or the skill registry."""
+        if func_name in self._scene_tool_names:
+            return await dispatcher.execute(self.state, func_name, func_args)
+        return await self.skill_registry.execute_tool(
+            func_name, func_args, self.state,
+        )
+
+    def _nudge_on_validation_errors(
+        self, tool_calls: list, retries: int,
+    ) -> bool:
+        """If ``validate_scene`` returned errors, nudge the LLM to fix them."""
+        for tool_call in tool_calls:
+            if tool_call.function.name != "validate_scene":
+                continue
+            for msg in reversed(self.conversation_history):
+                if msg.get("tool_call_id") != tool_call.id:
+                    continue
+                try:
+                    content = json.loads(msg["content"])
+                except (json.JSONDecodeError, TypeError):
+                    return False
+                if content.get("is_valid", True) or retries >= MAX_VALIDATION_RETRIES:
+                    return False
+                self.conversation_history.append({
+                    "role": "user",
+                    "content": (
+                        "The scene has validation errors. Please fix the "
+                        "issues listed above, then call validate_scene again."
+                    ),
+                })
+                logger.info(
+                    "Validation retry nudge (%d/%d)",
+                    retries + 1, MAX_VALIDATION_RETRIES,
+                )
+                return True
+        return False
+
+    def reset(self) -> None:
+        """Clear conversation history for a new session."""
+        self.conversation_history.clear()

bowerbot/cli.py

@@ -0,0 +1,430 @@
+# Copyright 2026 Binary Core LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""BowerBot CLI — natural language 3D scene assembly."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+import litellm
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.theme import Theme
+
+from bowerbot import __version__, dispatcher
+from bowerbot.agent import AgentRuntime
+from bowerbot.config import (
+    BOWERBOT_HOME,
+    GLOBAL_CONFIG_PATH,
+    LLMSettings,
+    SceneDefaults,
+    Settings,
+    ensure_home,
+    load_settings,
+    save_settings,
+)
+from bowerbot.project import Project
+from bowerbot.utils import stage_utils
+from bowerbot.skills.registry import SkillRegistry
+from bowerbot.state import SceneState
+from bowerbot.utils.naming_utils import safe_project_name
+
+theme = Theme({
+    "sf": "bold green",
+    "user": "bold cyan",
+    "info": "dim",
+})
+console = Console(theme=theme)
+
+
+def _build_state(
+    settings: Settings, project: Project | None = None,
+) -> SceneState:
+    """Build a SceneState, optionally binding it to *project*."""
+    state = SceneState(
+        scene_defaults=settings.scene_defaults,
+        library_dir=Path(settings.assets_dir),
+    )
+    if project is None:
+        return state
+
+    state.project = project
+    state.stage_path = project.scene_path
+
+    if project.scene_path.exists():
+        state.stage = stage_utils.open_stage(project.scene_path)
+        state.object_count = len(stage_utils.list_prims(state.stage))
+    return state
+
+
+def _build_registry(settings: Settings) -> SkillRegistry:
+    """Build a SkillRegistry with extension skills only."""
+    registry = SkillRegistry()
+    registry.load_from_settings(settings)
+    return registry
+
+
+@click.group()
+@click.version_option()
+def main() -> None:
+    """BowerBot — AI-powered 3D scene assembly using OpenUSD."""
+
+
+@main.command()
+@click.argument("name")
+def new(name: str) -> None:
+    """Create a new BowerBot project."""
+    settings = load_settings()
+    projects_dir = Path(settings.projects_dir)
+    projects_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        project = Project.create(projects_dir, name)
+        console.print(f"[sf]✅ Created project:[/] {project.name}")
+        console.print(f"   Path: {project.path}")
+        console.print("\n[info]Start working:[/]")
+        console.print(f"   cd {project.path}")
+        console.print("   bowerbot chat")
+    except FileExistsError:
+        console.print(f"[red]Project already exists:[/] {name}")
+
+
+@main.command(name="list")
+def list_projects() -> None:
+    """List all BowerBot projects."""
+    settings = load_settings()
+    projects = Project.list_projects(Path(settings.projects_dir))
+
+    if not projects:
+        console.print("[info]No projects yet. Create one with:[/]")
+        console.print("  bowerbot new my_project")
+        return
+
+    table = Table(title="BowerBot Projects")
+    table.add_column("Name", style="bold green")
+    table.add_column("Updated", style="dim")
+    table.add_column("Path", style="dim")
+
+    for p in projects:
+        table.add_row(p.name, p.meta.updated_at[:10], str(p.path))
+
+    console.print(table)
+
+
+@main.command()
+@click.argument("name")
+def open(name: str) -> None:
+    """Open a project and start an interactive session."""
+    settings = load_settings()
+    projects_dir = Path(settings.projects_dir)
+
+    project_path = projects_dir / name.lower().replace(" ", "_")
+    if not project_path.exists():
+        console.print(f"[red]Project not found:[/] {name}")
+        console.print("[info]Available projects:[/]")
+        for p in Project.list_projects(projects_dir):
+            console.print(f"  • {p.meta.name} ({p.path.name})")
+        return
+
+    project = Project.load(project_path)
+    _start_chat(settings, project)
+
+
+@main.command()
+def chat() -> None:
+    """Interactive scene building session.
+
+    If run inside a project directory, auto-loads that project.
+    Otherwise starts without a project (use 'new' to create one).
+    """
+    settings = load_settings()
+    project = Project.detect(Path.cwd())
+    if project:
+        console.print(f"[sf]Detected project:[/] {project.name}")
+    _start_chat(settings, project)
+
+
+def _format_object_summary(obj: dict) -> str:
+    """Format a scene object for the resume context message."""
+    path = obj["prim_path"]
+    pos = obj.get("position")
+    label = obj.get("asset") or obj.get("light_type") or obj.get("type", "unknown")
+    return f"  - {path} ({label}, position: {pos})"
+
+
+def _start_chat(settings: Settings, project: Project | None = None) -> None:
+    """Start an interactive chat session, optionally inside a project."""
+    state = _build_state(settings, project=project)
+    registry = _build_registry(settings)
+
+    status = f"[sf]BowerBot[/] v{__version__} — Interactive Scene Builder\n"
+    status += f"[info]Model:[/]  {settings.llm.model}\n"
+    status += f"[info]Skills:[/] {', '.join(registry.enabled_skills)}\n"
+
+    if project:
+        status += f"[info]Project:[/] {project.name}\n"
+        status += f"[info]Path:[/]    {project.path}\n"
+        if project.scene_path.exists():
+            status += (
+                f"[info]Scene:[/]   {project.meta.scene_file} "
+                f"({state.object_count} object(s))\n"
+            )
+    else:
+        status += "[info]Project:[/] none (use 'bowerbot new' to create one)\n"
+
+    status += "\n[info]Commands: 'quit' to exit, 'reset' to start a new session[/]"
+    console.print(Panel(status, title="[sf]BowerBot[/]", border_style="green"))
+
+    agent = AgentRuntime(
+        settings=settings, state=state, skill_registry=registry,
+    )
+
+    if project and project.scene_path.exists() and state.object_count > 0:
+        objects = stage_utils.list_prims(state.stage)
+        object_summary = "\n".join(
+            _format_object_summary(o) for o in objects
+        )
+        context = (
+            f"You are resuming project '{project.name}'. The scene is "
+            f"already open at {project.scene_path} with "
+            f"{len(objects)} object(s):\n{object_summary}\n"
+            f"The stage is loaded and ready — you do NOT need to call "
+            f"create_stage."
+        )
+        agent.conversation_history.append(
+            {"role": "system", "content": context},
+        )
+
+    asyncio.run(_chat_loop(agent, console))
+
+
+async def _chat_loop(agent: AgentRuntime, console: Console) -> None:
+    """Run the interactive chat loop."""
+    while True:
+        console.print()
+        try:
+            user_input = console.input("[user]You:[/] ").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\n[info]Goodbye![/]")
+            break
+
+        if not user_input:
+            continue
+        if user_input.lower() in ("quit", "exit", "q"):
+            console.print("[info]Goodbye![/]")
+            break
+        if user_input.lower() == "reset":
+            agent.reset()
+            console.print("[info]Session reset — starting fresh.[/]")
+            continue
+
+        try:
+            with console.status("[sf]BowerBot is thinking...[/]", spinner="dots"):
+                response = await agent.process(user_input)
+            console.print(f"\n[sf]BowerBot:[/] {response}")
+        except KeyboardInterrupt:
+            console.print("\n[info]Interrupted. Type 'quit' to exit.[/]")
+        except litellm.AuthenticationError:
+            console.print(
+                "\n[red]Authentication failed.[/] "
+                "Check your API key with 'bowerbot info'.",
+            )
+        except litellm.RateLimitError:
+            console.print(
+                "\n[yellow]Rate limited.[/] "
+                "Retries exhausted — wait a moment and try again.",
+            )
+        except litellm.APIConnectionError:
+            console.print(
+                "\n[red]Cannot reach API.[/] Check your network connection.",
+            )
+        except litellm.Timeout:
+            console.print(
+                "\n[yellow]Request timed out.[/] "
+                "Try again or increase request_timeout in config.",
+            )
+        except Exception as e:
+            console.print(f"\n[red]Error:[/] {e}")
+            console.print(
+                "[info]You can keep going or type 'reset' to start over.[/]",
+            )
+
+
+@main.command()
+@click.argument("prompt")
+def build(prompt: str) -> None:
+    """Build a USD scene from a single prompt (auto-creates a project)."""
+    settings = load_settings()
+
+    words = prompt.split()[:4]
+    project_name = " ".join(words)
+    projects_dir = Path(settings.projects_dir)
+    projects_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        project = Project.create(projects_dir, project_name)
+    except FileExistsError:
+        safe_name = safe_project_name(project_name)
+        project = Project.load(projects_dir / safe_name)
+
+    console.print("[sf]BowerBot[/] Building scene...")
+    console.print(f"  Prompt:   {prompt}")
+    console.print(f"  Model:    {settings.llm.model}")
+    console.print(f"  Project:  {project.name}")
+    console.print(f"  Path:     {project.path}")
+
+    state = _build_state(settings, project=project)
+    registry = _build_registry(settings)
+    console.print(f"  Skills:   {registry.enabled_skills}")
+
+    agent = AgentRuntime(
+        settings=settings, state=state, skill_registry=registry,
+    )
+
+    try:
+        response = asyncio.run(agent.process(prompt))
+        console.print(f"\n{response}")
+    except litellm.AuthenticationError:
+        console.print(
+            "\n[red]Authentication failed.[/] "
+            "Check your API key with 'bowerbot info'.",
+        )
+    except litellm.RateLimitError:
+        console.print(
+            "\n[yellow]Rate limited.[/] "
+            "Retries exhausted — wait a moment and try again.",
+        )
+    except litellm.APIConnectionError:
+        console.print(
+            "\n[red]Cannot reach API.[/] Check your network connection.",
+        )
+    except litellm.Timeout:
+        console.print(
+            "\n[yellow]Request timed out.[/] "
+            "Try again or increase request_timeout in config.",
+        )
+    except Exception as e:
+        console.print(f"\n[red]Error:[/] {e}")
+
+
+@main.command()
+def skills() -> None:
+    """List available and enabled skills."""
+    settings = load_settings()
+
+    scene_tools = dispatcher.get_tool_names()
+    console.print(f"[sf]Scene builder:[/] {len(scene_tools)} tools")
+    for name in sorted(scene_tools):
+        console.print(f"    - {name}")
+
+    registry = _build_registry(settings)
+
+    if registry.skill_count == 0:
+        console.print("\n[info]No extension skills enabled.[/]")
+        return
+
+    console.print("\n[sf]Extension skills:[/]")
+    for name in registry.enabled_skills:
+        tools = [
+            t["function"]["name"]
+            for t in registry.get_all_tools()
+            if t["function"]["name"].startswith(name)
+        ]
+        console.print(f"  • {name} ({len(tools)} tools)")
+        for tool_name in tools:
+            console.print(f"      - {tool_name}")
+
+
+@main.command()
+def info() -> None:
+    """Show current configuration."""
+    settings = load_settings()
+
+    console.print("[sf]BowerBot Configuration[/]")
+    console.print(f"  Model:           {settings.llm.model}")
+    console.print(f"  Temperature:     {settings.llm.temperature}")
+    console.print(f"  Max tokens:      {settings.llm.max_tokens}")
+    console.print(
+        f"  API key:         "
+        f"{'✅ set' if settings.get_api_key() else '❌ missing'}",
+    )
+    console.print(f"  Projects dir:    {settings.projects_dir}")
+    console.print(f"  Meters per unit: {settings.scene_defaults.meters_per_unit}")
+    console.print(f"  Up axis:         {settings.scene_defaults.up_axis}")
+    console.print(f"  Room bounds:     {settings.scene_defaults.default_room_bounds}")
+
+    skills_enabled = [k for k, v in settings.skills.items() if v.enabled]
+    console.print(f"  Skills enabled:  {skills_enabled or 'none'}")
+
+
+@main.command()
+def onboard() -> None:
+    """Set up BowerBot for first use."""
+    console.print(Panel(
+        "[sf]BowerBot[/] — First Time Setup\n\n"
+        "This will create your global configuration at:\n"
+        f"  [info]{BOWERBOT_HOME}[/]",
+        title="[sf]Setup[/]",
+        border_style="green",
+    ))
+
+    if GLOBAL_CONFIG_PATH.exists():
+        console.print(f"\n[info]Config already exists at {GLOBAL_CONFIG_PATH}[/]")
+        overwrite = console.input("Overwrite? (y/N): ").strip().lower()
+        if overwrite != "y":
+            console.print("[info]Keeping existing config.[/]")
+            return
+
+    ensure_home()
+
+    console.print("\n[sf]LLM Configuration[/]")
+    model = console.input("  Model [gpt-4.1]: ").strip() or "gpt-4.1"
+    api_key = console.input("  API key: ").strip()
+
+    if not api_key:
+        console.print(
+            "[yellow]Warning:[/] No API key provided. "
+            "BowerBot won't work without one.\n"
+            "You can add it later in ~/.bowerbot/config.json",
+        )
+
+    console.print("\n[sf]Directories[/]")
+    assets_dir = (
+        console.input("  Asset directory [./assets]: ").strip() or "./assets"
+    )
+    projects_dir = (
+        console.input("  Projects directory [./scenes]: ").strip() or "./scenes"
+    )
+
+    settings = Settings(
+        llm=LLMSettings(
+            model=model,
+            api_key=api_key,
+            temperature=0.1,
+            max_tokens=4096,
+        ),
+        scene_defaults=SceneDefaults(),
+        skills={},
+        assets_dir=assets_dir,
+        projects_dir=projects_dir,
+    )
+
+    save_settings(settings)
+
+    console.print(f"\n[sf]Config saved to {GLOBAL_CONFIG_PATH}[/]")
+    console.print(
+        "\n[info]Skills are extension packages you install separately. "
+        "After installing one (e.g. [sf]pip install bowerbot-skill-sketchfab[/]), "
+        "add its config to your config.json under the [sf]skills[/] block.[/]",
+    )
+    console.print("\n[info]You're ready to go! Try:[/]")
+    console.print("  [sf]bowerbot new my_first_scene[/]")
+    console.print("  [sf]bowerbot chat[/]")
+
+
+if __name__ == "__main__":
+    main()