apyrobo 3.0.0__py3-none-any.whl

apyrobo/__init__.py

@@ -0,0 +1,152 @@
+"""
+APYROBO — Open-source AI orchestration layer for robotics.
+
+Built on ROS 2. Model-agnostic. Hardware-agnostic.
+
+    from apyrobo import Agent, Robot, SafetyEnforcer
+
+    robot = Robot.discover("mock://turtlebot4")
+    agent = Agent(provider="rule")
+    result = agent.execute(task="deliver package to room 3", robot=robot)
+"""
+
+from apyrobo.__version__ import __version__
+
+from apyrobo.core.robot import Robot
+from apyrobo.core.health import ConnectionHealth
+from apyrobo.core.adapters import (
+    CapabilityAdapter, MockAdapter, GazeboAdapter, MQTTAdapter, HTTPAdapter,
+    list_adapters, register_adapter, register_adapter_class,
+)
+from apyrobo.core.schemas import RobotCapability, TaskRequest, TaskResult, AdapterState
+from apyrobo.skills.agent import (
+    Agent, AgentProvider, RuleBasedProvider, LLMProvider,
+    ToolCallingProvider, MultiTurnProvider, ClarificationNeeded,
+    build_constrained_prompt,
+)
+from apyrobo.skills.skill import Skill, BUILTIN_SKILLS
+from apyrobo.skills.decorators import skill, get_decorated_skills
+from apyrobo.skills.executor import SkillGraph, SkillExecutor, ExecutionState, SkillTimeout
+from apyrobo.safety.enforcer import (
+    SafetyEnforcer, SafetyPolicy, SafetyViolation, EscalationTimeout,
+    SpeedProfile, SafetyAuditEntry, FormalConstraintExporter,
+    POLICY_REGISTRY,
+)
+from apyrobo.safety.confidence import (
+    ConfidenceEstimator, ConfidenceReport, LowConfidenceError,
+)
+from apyrobo.swarm.bus import SwarmBus, SwarmMessage
+from apyrobo.swarm.coordinator import SwarmCoordinator
+from apyrobo.swarm.safety import SwarmSafety, ProximityViolation, DeadlockDetected
+from apyrobo.sensors.pipeline import SensorPipeline, WorldState, SensorReading
+from apyrobo.skills.library import SkillLibrary
+from apyrobo.skills.package import SkillPackage
+from apyrobo.skills.registry import SkillRegistry, PackageConflict, DependencyError
+from apyrobo.config import ApyroboConfig
+from apyrobo.inference.router import (
+    InferenceRouter, Urgency, CircuitState,
+    TokenBudget, PlanCache, ProviderHealth,
+)
+from apyrobo.observability import get_logger, trace_context, configure_logging
+from apyrobo.persistence import StateStore
+from apyrobo.costmap import CostmapChecker, MockCostmapChecker
+from apyrobo.auth import AuthManager, GuardedRobot, AuthError
+from apyrobo.task_queue import TaskQueue, QueuedTask
+from apyrobo.operations import (
+    BatteryMonitor, MapManager, TeleoperationBridge, WebhookEmitter,
+    ScheduledTaskRunner, OperationsApiServer, FleetDashboard,
+)
+from apyrobo.operations import BatteryMonitor, MapManager, TeleoperationBridge, WebhookEmitter
+from apyrobo.sim import (
+    GazeboNativeAdapter, MuJoCoAdapter, IsaacSimAdapter,
+    DomainRandomizationConfig, DomainRandomizer, RealityGapCalibrator,
+    SimToRealTransferPipeline,
+)
+
+# Ensure ROS 2 adapter is registered (import triggers @register_adapter).
+# When rclpy is missing, ros2_bridge emits a warnings.warn and _HAS_ROS2=False,
+# so the real ROS2Adapter is not registered. We register a stub instead so that
+# Robot.discover("ros2://...") raises a clear RuntimeError rather than a cryptic
+# "No adapter registered for scheme 'ros2'" message.
+import warnings as _warnings
+_ros2_loaded = False
+with _warnings.catch_warnings():
+    _warnings.simplefilter("ignore")  # suppress ros2_bridge's own rclpy ImportWarning
+    try:
+        from apyrobo.core import ros2_bridge as _ros2_bridge  # noqa: F401
+        _ros2_loaded = True
+    except Exception:
+        pass
+
+if not _ros2_loaded:
+    _warnings.warn(
+        "ROS 2 adapter not available (rclpy not installed). "
+        "Install inside a ROS 2 environment or use the Docker image. "
+        "Available without ROS 2: mock://, gazebo://, gazebo_native://",
+        stacklevel=2,
+    )
+
+from apyrobo.core.adapters import _ADAPTER_REGISTRY as _REG, CapabilityAdapter as _CA
+
+if "ros2" not in _REG:
+    class _ROS2Unavailable(_CA):
+        """Stub adapter that raises a helpful error when rclpy is not installed."""
+
+        def __init__(self, robot_name: str, **kwargs: object) -> None:
+            raise RuntimeError(
+                "The ros2:// adapter requires rclpy, which is only available inside "
+                "the APYROBO Docker container.\n\n"
+                "Quick fix:\n"
+                "  docker compose -f docker/docker-compose.yml exec apyrobo bash\n\n"
+                "Without Docker, use mock:// for testing or gazebo:// for sim.\n"
+                "See docs/QUICKSTART.md for the full setup guide."
+            )
+
+        def get_capabilities(self):  # type: ignore[override]
+            raise NotImplementedError
+
+        def move(self, x: float, y: float, speed=None) -> None:  # type: ignore[override]
+            raise NotImplementedError
+
+        def stop(self) -> None:
+            raise NotImplementedError
+
+    _REG["ros2"] = _ROS2Unavailable
+
+del _REG, _CA
+
+__all__ = [
+    "__version__",
+    "Robot",
+    "Agent",
+    "skill",
+    "get_decorated_skills",
+    "SkillLibrary",
+    "RobotCapability",
+    "TaskRequest",
+    "TaskResult",
+    "AdapterState",
+    "CapabilityAdapter",
+    "MockAdapter",
+    "GazeboAdapter",
+    "MQTTAdapter",
+    "HTTPAdapter",
+    "GazeboNativeAdapter",
+    "MuJoCoAdapter",
+    "IsaacSimAdapter",
+    "list_adapters",
+    "register_adapter",
+    "register_adapter_class",
+    "Skill",
+    "BUILTIN_SKILLS",
+    "SkillGraph",
+    "SkillExecutor",
+    "SafetyEnforcer",
+    "SafetyPolicy",
+    "SafetyViolation",
+    "ScheduledTaskRunner",
+    "OperationsApiServer",
+    "FleetDashboard",
+    "CostmapChecker",
+    "MockCostmapChecker",
+]

apyrobo/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running APYROBO as ``python -m apyrobo``."""
+
+from apyrobo.cli import main
+
+if __name__ == "__main__":
+    main()

apyrobo/__version__.py

@@ -0,0 +1,3 @@
+# Single source of truth for the package version.
+# Imported by apyrobo/__init__.py and read by scripts/bump_version.sh.
+__version__ = "3.0.0"

apyrobo/agents/__init__.py

@@ -0,0 +1,17 @@
+"""
+Agents — stateful LLM agents for robot task orchestration.
+
+Provides multi-turn conversation agents and tool-calling agents
+that sit above the InferenceRouter and skills layers.
+"""
+
+from apyrobo.agents.multiturn import ConversationHistory, ConversationMessage, MultiTurnAgent
+from apyrobo.agents.tool_agent import SkillTool, ToolCallingAgent
+
+__all__ = [
+    "ConversationMessage",
+    "ConversationHistory",
+    "MultiTurnAgent",
+    "SkillTool",
+    "ToolCallingAgent",
+]

apyrobo/agents/multiturn.py

@@ -0,0 +1,163 @@
+"""
+Multi-turn Agent — stateful conversation with clarification dialogue.
+
+Maintains conversation history and sends full context to the LLM on each
+turn, enabling robots to ask for clarification when a task is ambiguous.
+
+Classes:
+    ConversationMessage  — a single turn (role + content + timestamp)
+    ConversationHistory  — ordered list of messages with token-aware truncation
+    MultiTurnAgent       — agent that answers via LLM or MockLLM fallback
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Rough tokens-per-char estimate for context window truncation.
+_CHARS_PER_TOKEN = 4
+
+
+@dataclass
+class ConversationMessage:
+    """A single message in a multi-turn conversation."""
+
+    role: str  # "user" | "assistant" | "system"
+    content: str
+    timestamp: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "metadata": self.metadata,
+        }
+
+
+class ConversationHistory:
+    """
+    Ordered history of conversation messages.
+
+    Supports token-budget truncation: get_context() drops the oldest
+    non-system messages first until the total fits within max_tokens.
+    """
+
+    def __init__(self) -> None:
+        self._messages: list[ConversationMessage] = []
+
+    def add(self, msg: ConversationMessage) -> None:
+        self._messages.append(msg)
+
+    def get_context(self, max_tokens: int = 4096) -> list[dict[str, Any]]:
+        """
+        Return messages as LLM-compatible dicts, truncated to fit max_tokens.
+
+        System messages are always kept; oldest user/assistant messages are
+        dropped first when over budget.
+        """
+        system_msgs = [m for m in self._messages if m.role == "system"]
+        other_msgs = [m for m in self._messages if m.role != "system"]
+
+        # Start with system messages (always included)
+        kept = list(system_msgs)
+        budget = max_tokens - sum(len(m.content) // _CHARS_PER_TOKEN for m in kept)
+
+        # Add other messages newest-first until budget exhausted
+        for msg in reversed(other_msgs):
+            cost = len(msg.content) // _CHARS_PER_TOKEN + 1
+            if budget >= cost:
+                kept.append(msg)
+                budget -= cost
+            else:
+                break
+
+        # Sort by timestamp to restore chronological order
+        kept.sort(key=lambda m: m.timestamp)
+        return [{"role": m.role, "content": m.content} for m in kept]
+
+    def clear(self) -> None:
+        self._messages.clear()
+
+    def to_dict(self) -> list[dict[str, Any]]:
+        return [m.to_dict() for m in self._messages]
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+
+def _mock_llm_reply(messages: list[dict[str, Any]], context: dict[str, Any] | None) -> str:
+    """Deterministic mock LLM for use when litellm is not configured."""
+    last_user = next(
+        (m["content"] for m in reversed(messages) if m["role"] == "user"), ""
+    )
+    ctx_note = f" [context keys: {list(context)}]" if context else ""
+    return f"Mock reply to: {last_user!r}{ctx_note}"
+
+
+class MultiTurnAgent:
+    """
+    Stateful agent that maintains conversation history across turns.
+
+    Uses litellm if available and configured; falls back to MockLLM for
+    offline/test use.
+
+    Usage:
+        agent = MultiTurnAgent(system_prompt="You are a robot assistant.")
+        reply = agent.chat("navigate to the kitchen")
+        follow = agent.chat("actually, go to the living room instead")
+    """
+
+    def __init__(self, model: str = "gpt-4o", system_prompt: str = "") -> None:
+        self.model = model
+        self.history = ConversationHistory()
+        if system_prompt:
+            self.history.add(
+                ConversationMessage(role="system", content=system_prompt)
+            )
+
+    def chat(self, message: str, context: dict[str, Any] | None = None) -> str:
+        """
+        Send a message and return the assistant's reply.
+
+        Args:
+            message: User message text.
+            context:  Optional dict merged into the user message metadata.
+
+        Returns:
+            Assistant reply string.
+        """
+        self.history.add(
+            ConversationMessage(role="user", content=message, metadata=context or {})
+        )
+
+        messages = self.history.get_context(max_tokens=4096)
+        reply = self._call_llm(messages, context)
+
+        self.history.add(ConversationMessage(role="assistant", content=reply))
+        return reply
+
+    def _call_llm(
+        self, messages: list[dict[str, Any]], context: dict[str, Any] | None
+    ) -> str:
+        try:
+            import litellm  # type: ignore[import]
+            response = litellm.completion(
+                model=self.model,
+                messages=messages,
+                max_tokens=512,
+            )
+            return response.choices[0].message.content or ""
+        except Exception as exc:
+            logger.debug("litellm unavailable (%s), using mock LLM", exc)
+            return _mock_llm_reply(messages, context)
+
+    def reset(self) -> None:
+        """Clear conversation history."""
+        self.history.clear()

apyrobo/agents/tool_agent.py

@@ -0,0 +1,151 @@
+"""
+Tool-calling Agent — LLM that directly invokes skills via function-calling.
+
+The agent converts a list of SkillTool definitions into LLM tool/function
+specs, sends the task to the LLM, executes any tool calls the model
+requests, and returns the final text answer.
+
+Falls back to a deterministic mock when litellm is not configured.
+
+Classes:
+    SkillTool         — descriptor for one executable skill
+    ToolCallingAgent  — agent that uses function-calling to run skills
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SkillTool:
+    """A skill exposed to the LLM as a callable tool."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema object
+    executor: Callable[..., Any]  # sync function called with **params
+
+
+def _tools_to_litellm(tools: list[SkillTool]) -> list[dict[str, Any]]:
+    """Convert SkillTools to litellm-compatible tool definitions."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters,
+            },
+        }
+        for t in tools
+    ]
+
+
+def _mock_run(task: str, tools: list[SkillTool]) -> str:
+    """
+    Deterministic mock: execute the first tool with default params,
+    then return a canned summary.
+    """
+    if not tools:
+        return f"Mock: no tools available for task {task!r}"
+    tool = tools[0]
+    # Build minimal args from required properties
+    props = tool.parameters.get("properties", {})
+    required = tool.parameters.get("required", [])
+    kwargs: dict[str, Any] = {}
+    for key in required:
+        schema = props.get(key, {})
+        t = schema.get("type", "string")
+        kwargs[key] = 0.0 if t == "number" else ("mock_value" if t == "string" else None)
+    result = tool.executor(**kwargs)
+    return f"Mock: executed {tool.name!r} → {result}"
+
+
+class ToolCallingAgent:
+    """
+    Agent that uses LLM function-calling to invoke skills.
+
+    Usage:
+        def move_robot(x: float, y: float):
+            robot.move(x, y)
+            return "moved"
+
+        tool = SkillTool(
+            name="navigate_to",
+            description="Move robot to (x, y)",
+            parameters={
+                "type": "object",
+                "properties": {"x": {"type": "number"}, "y": {"type": "number"}},
+                "required": ["x", "y"],
+            },
+            executor=move_robot,
+        )
+        agent = ToolCallingAgent(tools=[tool])
+        result = agent.run("go to position 3, 5")
+    """
+
+    def __init__(self, tools: list[SkillTool], model: str = "gpt-4o") -> None:
+        self.tools = tools
+        self.model = model
+        self._tool_map: dict[str, SkillTool] = {t.name: t for t in tools}
+
+    def run(self, task: str) -> str:
+        """
+        Execute a task, invoking tools as needed.
+
+        Returns the final natural-language answer.
+        """
+        try:
+            import litellm  # type: ignore[import]
+            return self._run_with_litellm(task, litellm)
+        except Exception as exc:
+            logger.debug("litellm unavailable (%s), using mock", exc)
+            return _mock_run(task, self.tools)
+
+    def _run_with_litellm(self, task: str, litellm: Any) -> str:
+        messages: list[dict[str, Any]] = [{"role": "user", "content": task}]
+        tool_defs = _tools_to_litellm(self.tools)
+
+        for _ in range(10):  # guard against infinite loops
+            response = litellm.completion(
+                model=self.model,
+                messages=messages,
+                tools=tool_defs,
+                tool_choice="auto",
+            )
+            choice = response.choices[0]
+            finish = choice.finish_reason
+            msg = choice.message
+
+            # Add assistant message to context
+            messages.append({"role": "assistant", "content": msg.content or "", "tool_calls": getattr(msg, "tool_calls", None)})
+
+            if finish == "tool_calls" and msg.tool_calls:
+                for tc in msg.tool_calls:
+                    fn_name = tc.function.name
+                    fn_args = json.loads(tc.function.arguments or "{}")
+                    tool = self._tool_map.get(fn_name)
+                    if tool is None:
+                        result = f"Unknown tool: {fn_name}"
+                    else:
+                        try:
+                            result = str(tool.executor(**fn_args))
+                        except Exception as e:
+                            result = f"Error: {e}"
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "name": fn_name,
+                        "content": result,
+                    })
+            else:
+                # Final answer
+                return msg.content or ""
+
+        return "Tool-calling agent exceeded iteration limit."

apyrobo/api/__init__.py

@@ -0,0 +1,14 @@
+"""
+REST API Gateway — HTTP interface for external systems to submit tasks.
+
+Exposes a FastAPI application with:
+    POST /tasks              — submit a task
+    GET  /tasks/{id}         — get task status
+    GET  /robots             — list registered robots
+    POST /robots/{id}/skills/{skill} — execute a skill directly
+    GET  /health             — health check
+"""
+
+from apyrobo.api.app import create_app
+
+__all__ = ["create_app"]

apyrobo/api/app.py

@@ -0,0 +1,166 @@
+"""
+REST API Gateway — FastAPI application.
+
+Authentication:
+    All mutating endpoints require an X-API-Key header validated against
+    the APYROBO_API_KEY environment variable (or a key supplied to
+    create_app()).  GET /health is public.
+
+In-memory stores:
+    Tasks and robots are kept in plain dicts — no database required.
+
+Usage:
+    from apyrobo.api.app import create_app
+    app = create_app(api_key="secret")
+
+    # with uvicorn:
+    # uvicorn apyrobo.api.app:app
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from typing import Any
+
+try:
+    from fastapi import Depends, FastAPI, HTTPException, Header, status
+    from fastapi.responses import JSONResponse
+    from pydantic import BaseModel
+    _FASTAPI_AVAILABLE = True
+except ImportError:
+    _FASTAPI_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+if _FASTAPI_AVAILABLE:
+    class TaskRequest(BaseModel):
+        skill: str
+        params: dict[str, Any] = {}
+        robot_id: str = ""
+
+    class SkillRequest(BaseModel):
+        params: dict[str, Any] = {}
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def create_app(api_key: str | None = None) -> "FastAPI":
+    """
+    Create and return the FastAPI application.
+
+    Args:
+        api_key: If provided, all authenticated endpoints require this key
+                 in the X-API-Key header.  Defaults to the APYROBO_API_KEY
+                 env variable, or an empty string (no auth).
+    """
+    if not _FASTAPI_AVAILABLE:
+        raise ImportError("fastapi and pydantic are required for the REST API gateway")
+
+    _api_key: str = api_key or os.getenv("APYROBO_API_KEY", "")
+
+    # In-memory state
+    _tasks: dict[str, dict[str, Any]] = {}
+    _robots: dict[str, dict[str, Any]] = {}
+
+    app = FastAPI(title="Apyrobo API", version="0.4.0")
+
+    # ------------------------------------------------------------------
+    # Auth dependency
+    # ------------------------------------------------------------------
+
+    def require_auth(x_api_key: str = Header(default="")) -> None:
+        if _api_key and x_api_key != _api_key:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or missing X-API-Key",
+            )
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    @app.get("/health")
+    def health() -> dict[str, Any]:
+        return {"status": "ok", "tasks": len(_tasks), "robots": len(_robots)}
+
+    # ------------------------------------------------------------------
+    # Tasks
+    # ------------------------------------------------------------------
+
+    @app.post("/tasks", status_code=status.HTTP_201_CREATED,
+              dependencies=[Depends(require_auth)])
+    def submit_task(req: TaskRequest) -> dict[str, Any]:
+        task_id = str(uuid.uuid4())
+        task = {
+            "task_id": task_id,
+            "skill": req.skill,
+            "params": req.params,
+            "robot_id": req.robot_id,
+            "status": "queued",
+            "created_at": time.time(),
+            "updated_at": time.time(),
+            "result": None,
+        }
+        _tasks[task_id] = task
+        return task
+
+    @app.get("/tasks/{task_id}", dependencies=[Depends(require_auth)])
+    def get_task(task_id: str) -> dict[str, Any]:
+        task = _tasks.get(task_id)
+        if task is None:
+            raise HTTPException(status_code=404, detail=f"Task {task_id!r} not found")
+        return task
+
+    # ------------------------------------------------------------------
+    # Robots
+    # ------------------------------------------------------------------
+
+    @app.get("/robots", dependencies=[Depends(require_auth)])
+    def list_robots() -> list[dict[str, Any]]:
+        return list(_robots.values())
+
+    @app.post("/robots/{robot_id}/skills/{skill}",
+              dependencies=[Depends(require_auth)])
+    def execute_skill(robot_id: str, skill: str, req: SkillRequest) -> dict[str, Any]:
+        # Register the robot if not yet seen
+        if robot_id not in _robots:
+            _robots[robot_id] = {
+                "robot_id": robot_id,
+                "registered_at": time.time(),
+                "capabilities": [],
+            }
+
+        task_id = str(uuid.uuid4())
+        task = {
+            "task_id": task_id,
+            "skill": skill,
+            "params": req.params,
+            "robot_id": robot_id,
+            "status": "queued",
+            "created_at": time.time(),
+            "updated_at": time.time(),
+            "result": None,
+        }
+        _tasks[task_id] = task
+        return {"task_id": task_id, "status": "queued"}
+
+    # Expose stores for testing
+    app.state.tasks = _tasks
+    app.state.robots = _robots
+
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Default app instance (for uvicorn apyrobo.api.app:app)
+# ---------------------------------------------------------------------------
+
+if _FASTAPI_AVAILABLE:
+    app = create_app()