maple-mcp 0.1.0__py3-none-any.whl

maple/__init__.py

@@ -0,0 +1,3 @@
+"""MAPLE — Model-Agnostic Platform for Laboratory Experiments."""
+
+__version__ = "0.1.0"

maple/attach.py

@@ -0,0 +1,128 @@
+"""MAPLE Attach TUI — tail live logs from running services."""
+
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+from textual.containers import Grid
+from textual.widgets import RichLog, Static
+
+LOG_DIR = Path.home() / ".maple" / "logs"
+
+
+class ServiceLogPane(Static):
+    """A single service's log pane with status header and scrollable log."""
+
+    DEFAULT_CSS = """
+    ServiceLogPane {
+        border: solid gray;
+        height: 1fr;
+    }
+    ServiceLogPane Static {
+        height: 1;
+        background: $panel;
+        padding: 0 1;
+    }
+    ServiceLogPane RichLog {
+        height: 1fr;
+    }
+    """
+
+    def __init__(self, service_name: str, **kwargs):
+        super().__init__(**kwargs)
+        self.service_name = service_name
+
+    def compose(self) -> ComposeResult:
+        yield Static(f"[green]● {self.service_name}[/]", id=f"status-{self.service_name}")
+        yield RichLog(id=f"log-{self.service_name}", highlight=True, markup=False, wrap=True)
+
+
+class MapleAttachApp(App):
+    """TUI for tailing MAPLE service logs in split panes."""
+
+    TITLE = "MAPLE — Service Logs"
+    CSS = """
+    Grid { grid-size: 2; height: 1fr; }
+    """
+    BINDINGS = [("q", "quit", "Quit"), ("ctrl+c", "quit", "Quit")]
+
+    def __init__(self, services: list[str] = None, **kwargs):
+        super().__init__(**kwargs)
+        self._services = services or self._discover_services()
+
+    def _discover_services(self) -> list[str]:
+        """Find services that are currently running (have active PIDs)."""
+        pid_dir = Path.home() / ".maple" / "pids"
+        if not pid_dir.exists():
+            return []
+        return [f.stem for f in sorted(pid_dir.glob("*.pid"))]
+
+    def compose(self) -> ComposeResult:
+        if not self._services:
+            yield Static("[dim]No services found. Run 'maple serve' first.[/]")
+            return
+        with Grid():
+            for name in self._services:
+                yield ServiceLogPane(name, id=f"pane-{name}")
+
+    async def on_mount(self) -> None:
+        self._offsets: dict[str, int] = {}
+        for name in self._services:
+            path = LOG_DIR / f"{name}.log"
+            path.touch(exist_ok=True)
+            self._offsets[name] = path.stat().st_size
+            self._show_tail(path, self.query_one(f"#log-{name}", RichLog), lines=20)
+        # Single watcher on the logs directory
+        self.run_worker(self._watch_logs(), exclusive=True)
+
+    async def _watch_logs(self) -> None:
+        """Poll log files for changes every 500ms. Simple and reliable."""
+        import asyncio
+
+        try:
+            while True:
+                await asyncio.sleep(0.5)
+                for name in self._services:
+                    path = LOG_DIR / f"{name}.log"
+                    if not path.exists():
+                        continue
+                    current_size = path.stat().st_size
+                    if current_size != self._offsets.get(name, 0):
+                        log = self.query_one(f"#log-{name}", RichLog)
+                        self._offsets[name] = self._flush_new_lines(
+                            path, log, self._offsets[name]
+                        )
+        except Exception:
+            pass
+
+    def _show_tail(self, path: Path, log: RichLog, lines: int = 20):
+        """Show the last N lines of the file on attach."""
+        try:
+            content = path.read_text(errors="replace")
+            recent = content.splitlines()[-lines:]
+            for line in recent:
+                log.write(line)
+        except Exception:
+            pass
+
+    def _flush_new_lines(self, path: Path, log: RichLog, offset: int) -> int:
+        """Read new content since last offset and write to log."""
+        try:
+            size = path.stat().st_size
+            if size < offset:
+                # File was truncated/rotated
+                offset = 0
+            with open(path, "r", errors="replace") as f:
+                f.seek(offset)
+                new_data = f.read()
+                new_offset = f.tell()
+            for line in new_data.splitlines():
+                log.write(line)
+            return new_offset
+        except Exception:
+            return offset
+
+
+def run_attach(services: list[str] = None):
+    """Launch the attach TUI."""
+    app = MapleAttachApp(services=services)
+    app.run()

maple/auth.py

@@ -0,0 +1,63 @@
+"""MAPLE authentication — auto-generated device tokens for session identity."""
+
+import os
+import re
+import uuid
+from pathlib import Path
+
+
+CREDENTIALS_FILE = Path.home() / ".maple" / "credentials"
+_UUID_PATTERN = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$')
+
+
+def get_or_create_token() -> str:
+    """Get the device token, creating one on first run.
+    
+    Tokens are UUIDv4 strings stored in ~/.maple/credentials.
+    Used as bearer tokens for MCP server auth, keying session state.
+    
+    Returns:
+        The device's unique token string.
+    """
+    if CREDENTIALS_FILE.exists():
+        token = CREDENTIALS_FILE.read_text().strip()
+        if token and is_valid_token(token):
+            return token
+
+    # Generate new token
+    token = str(uuid.uuid4())
+    CREDENTIALS_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    # Atomic write: write to temp file then rename
+    import tempfile
+    fd, tmp_path = tempfile.mkstemp(dir=CREDENTIALS_FILE.parent, prefix=".maple_cred_")
+    try:
+        os.write(fd, token.encode())
+        os.fchmod(fd, 0o600)
+        os.close(fd)
+        os.replace(tmp_path, CREDENTIALS_FILE)
+    except Exception:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        # Fallback: direct write
+        CREDENTIALS_FILE.write_text(token)
+        try:
+            os.chmod(CREDENTIALS_FILE, 0o600)
+        except OSError:
+            pass
+
+    return token
+
+
+def is_valid_token(token: str) -> bool:
+    """Validate that a token is a well-formed UUIDv4.
+    
+    Prevents arbitrary/malformed strings from becoming dict keys.
+    """
+    return bool(_UUID_PATTERN.match(token.lower()))

maple/cli.py

@@ -0,0 +1,220 @@
+"""MAPLE CLI — Command-line interface for serving and chatting with agents."""
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="maple",
+    help="MAPLE — Model-Agnostic Platform for Laboratory Experiments",
+    no_args_is_help=True,
+)
+serve_app = typer.Typer(help="Start MAPLE services in the background.")
+chat_app = typer.Typer(help="Chat with a MAPLE agent via TUI.")
+app.add_typer(serve_app, name="serve")
+app.add_typer(chat_app, name="chat")
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# maple serve <subcommand>
+# ---------------------------------------------------------------------------
+
+
+@serve_app.command("all")
+def serve_all(
+    dev: bool = typer.Option(False, "--dev", help="Enable auto-reload on file changes"),
+    config: str = typer.Option("maple.config.yaml", help="Path to config file"),
+):
+    """Start all MCP servers and agents (Operator + Overseer)."""
+    _do_serve(agent=None, stub=False, dev=dev, config=config)
+
+
+@serve_app.command("operator")
+def serve_operator(
+    dev: bool = typer.Option(False, "--dev", help="Enable auto-reload on file changes"),
+    config: str = typer.Option("maple.config.yaml", help="Path to config file"),
+):
+    """Start Operator MCP server and agent."""
+    _do_serve(agent="operator", stub=False, dev=dev, config=config)
+
+
+@serve_app.command("overseer")
+def serve_overseer(
+    dev: bool = typer.Option(False, "--dev", help="Enable auto-reload on file changes"),
+    config: str = typer.Option("maple.config.yaml", help="Path to config file"),
+):
+    """Start Overseer MCP server and agent."""
+    _do_serve(agent="overseer", stub=False, dev=dev, config=config)
+
+
+@serve_app.command("stub")
+def serve_stub(
+    dev: bool = typer.Option(False, "--dev", help="Enable auto-reload on file changes"),
+    config: str = typer.Option("maple.config.yaml", help="Path to config file"),
+):
+    """Start full demo stack (stub node + Operator MCP + mock agent)."""
+    _do_serve(agent=None, stub=True, dev=dev, config=config)
+
+
+@serve_app.command("mock")
+def serve_mock(
+    dev: bool = typer.Option(False, "--dev", help="Enable auto-reload on file changes"),
+):
+    """Start mock agent only (for demo/testing)."""
+    _do_serve(agent="mock", stub=False, dev=dev, config="maple.config.yaml")
+
+
+def _do_serve(agent: str = None, stub: bool = False, dev: bool = False, config: str = "maple.config.yaml"):
+    """Shared serve logic."""
+    from dotenv import load_dotenv
+    load_dotenv(override=True)
+
+    from maple.services import start_services
+
+    started = start_services(agent=agent, config=config, stub=stub, dev=dev)
+
+    if not started:
+        console.print("[red]No services to start.[/red]")
+        raise typer.Exit(1)
+
+    console.print()
+    for name, port, pid in started:
+        console.print(f"  [green]✓[/green] {name:20s} :{port}  (pid {pid})")
+    console.print()
+    if dev:
+        console.print("[yellow]Dev mode: services will auto-reload on file changes[/yellow]")
+    console.print("[dim]Logs: ~/.maple/logs/[/dim]")
+    console.print("[dim]Stop: maple down[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# maple chat <subcommand>
+# ---------------------------------------------------------------------------
+
+
+@chat_app.command("operator")
+def chat_operator(
+    host: str = typer.Option("localhost", help="Agent service host"),
+    resume: bool = typer.Option(False, "--resume", help="Resume most recent operator session"),
+):
+    """Chat with the Operator agent."""
+    from dotenv import load_dotenv
+    load_dotenv(override=True)
+    from maple.tui import run_chat
+    session_id = _get_session_id("operator", resume)
+    run_chat(agent="operator", host=host, session_id=session_id)
+
+
+@chat_app.command("overseer")
+def chat_overseer(
+    host: str = typer.Option("localhost", help="Agent service host"),
+    resume: bool = typer.Option(False, "--resume", help="Resume most recent overseer session"),
+):
+    """Chat with the Overseer agent."""
+    from dotenv import load_dotenv
+    load_dotenv(override=True)
+    from maple.tui import run_chat
+    session_id = _get_session_id("overseer", resume)
+    run_chat(agent="overseer", host=host, session_id=session_id)
+
+
+def _get_session_id(agent: str, resume: bool) -> str:
+    """Get or create a session ID for the chat.
+    
+    If resume=True, finds the most recent session file for the agent.
+    Otherwise generates a new UUID.
+    """
+    import uuid
+    from pathlib import Path
+
+    sessions_dir = Path.home() / ".maple" / "sessions" / agent
+
+    if resume and sessions_dir.exists():
+        session_dirs = [d for d in sessions_dir.iterdir() if d.is_dir() and d.name.startswith("session_")]
+        if session_dirs:
+            latest = max(session_dirs, key=lambda d: d.stat().st_mtime)
+            # Extract UUID from "session_{uuid}" directory name
+            session_id = latest.name.removeprefix("session_")
+            console.print(f"[dim]Resuming session: {session_id[:8]}...[/dim]")
+            return session_id
+        else:
+            console.print("[dim]No previous session found. Starting new.[/dim]")
+
+    return str(uuid.uuid4())
+
+
+# ---------------------------------------------------------------------------
+# maple down
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def down():
+    """Stop all running MAPLE services."""
+    from maple.services import stop_services
+
+    stopped = stop_services()
+
+    if stopped:
+        console.print(f"[green]✓[/green] Stopped {len(stopped)} service(s): {', '.join(stopped)}")
+    else:
+        console.print("[dim]No running services found.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# maple logs
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def logs():
+    """View live service logs in a TUI (tail mode)."""
+    from maple.attach import run_attach
+    run_attach()
+
+
+# ---------------------------------------------------------------------------
+# maple status
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def status():
+    """Check status of running MAPLE services."""
+    import httpx
+    from maple.services import get_status
+
+    running = get_status()
+
+    if not running:
+        console.print("[dim]No MAPLE services registered. Run 'maple serve' first.[/dim]")
+        return
+
+    console.print()
+    for name, pid, is_running in running:
+        if is_running:
+            console.print(f"  [green]✓[/green] {name:20s} (pid {pid})")
+        else:
+            console.print(f"  [red]✗[/red] {name:20s} (pid {pid} — dead)")
+    console.print()
+
+    # Also try pinging known endpoints
+    endpoints = {
+        "operator-mcp": "http://localhost:8102/ping",
+        "overseer-mcp": "http://localhost:8103/ping",
+        "operator-agent": "http://localhost:8202/ping",
+        "overseer-agent": "http://localhost:8203/ping",
+    }
+
+    for name, url in endpoints.items():
+        try:
+            resp = httpx.get(url, timeout=2)
+            if resp.status_code == 200:
+                console.print(f"  [green]●[/green] {name} responding")
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    app()

maple/config.py

@@ -0,0 +1,189 @@
+"""Configuration system for MAPLE."""
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class PostActionHook(BaseModel):
+    """A MADSci node action to call after each operator action."""
+
+    node: str
+    action: str
+    args: dict = {}
+
+
+class ExperimentConfig(BaseModel):
+    """Experiment brief template."""
+
+    name: str = "Untitled Experiment"
+    objective: str = ""
+    constraints: list[str] = []
+
+
+class OperatorConfig(BaseModel):
+    """Operator agent configuration."""
+
+    vision_backend: str = ""  # "module:ClassName" or empty for StubBackend
+    custom_tools: list[str] = []  # ["module:function_name", ...] to register at startup
+    post_action_hooks: list[PostActionHook] = []
+    prompt: str = ""  # Path to custom prompt file, or empty for default
+
+
+class OverseerConfig(BaseModel):
+    """Overseer agent configuration."""
+
+    custom_tools: list[str] = []  # ["module:function_name", ...] to register at startup
+    prompt: str = ""  # Path to custom prompt file, or empty for default
+
+
+class MapleConfig(BaseModel):
+    """Root MAPLE configuration."""
+
+    experiment: ExperimentConfig = ExperimentConfig()
+    operator: OperatorConfig = OperatorConfig()
+    overseer: OverseerConfig = OverseerConfig()
+
+
+# ---------------------------------------------------------------------------
+# Loader
+# ---------------------------------------------------------------------------
+
+
+def load_config(path: Optional[Path] = None) -> MapleConfig:
+    """Load MAPLE configuration from a YAML file.
+
+    Args:
+        path: Path to config file. Defaults to maple.config.yaml in current directory.
+
+    Returns:
+        Validated MapleConfig instance.
+    """
+    path = path or Path("maple.config.yaml")
+    if not path.exists():
+        return MapleConfig()
+    data = yaml.safe_load(path.read_text())
+    return MapleConfig(**(data or {}))
+
+
+# ---------------------------------------------------------------------------
+# Dynamic Import
+# ---------------------------------------------------------------------------
+
+
+def import_string(dotted_path: str):
+    """Import a class or object from a 'module:ClassName' string.
+
+    Supports both colon-separated ('vision:BlockSortingVision') and
+    dot-separated ('vision.BlockSortingVision') formats.
+
+    If the module is a relative file path (e.g., 'vision' resolving to
+    './vision.py'), the current directory is added to sys.path temporarily.
+
+    Args:
+        dotted_path: Import path in 'module:Class' or 'module.Class' format.
+
+    Returns:
+        The imported class or object.
+    """
+    if ":" in dotted_path:
+        module_path, class_name = dotted_path.rsplit(":", 1)
+    else:
+        module_path, _, class_name = dotted_path.rpartition(".")
+
+    if not module_path or not class_name:
+        raise ImportError(f"Invalid import path: '{dotted_path}'. Use 'module:ClassName' format.")
+
+    # Support relative imports from CWD
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as e:
+        raise ImportError(f"Cannot import module '{module_path}' from '{dotted_path}'") from e
+
+    try:
+        return getattr(module, class_name)
+    except AttributeError as e:
+        raise ImportError(f"Module '{module_path}' has no attribute '{class_name}'") from e
+
+
+def load_vision_backend(config: MapleConfig):
+    """Load the VisionBackend class from config and instantiate it.
+
+    Args:
+        config: Loaded MapleConfig.
+
+    Returns:
+        A VisionBackend instance. StubBackend if no backend specified.
+    """
+    from maple.vision import StubBackend
+
+    backend_path = config.operator.vision_backend
+    if not backend_path:
+        return StubBackend()
+
+    cls = import_string(backend_path)
+    return cls()
+
+
+def load_custom_tools(config: MapleConfig):
+    """Load and register custom MCP tools from config.
+
+    Each entry in config.operator.custom_tools should be a "module:function"
+    string. The function must already be decorated with @mcp.tool, OR it will
+    be registered programmatically.
+
+    Args:
+        config: Loaded MapleConfig.
+    """
+    if not config.operator.custom_tools:
+        return
+
+    from maple.operator.server import mcp
+
+    for tool_path in config.operator.custom_tools:
+        try:
+            func = import_string(tool_path)
+            # If not already registered, register it
+            if not hasattr(func, "__mcp_tool__"):
+                mcp.tool(func)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to load custom tool '{tool_path}': {e}. "
+                f"Check the path in maple.config.yaml under operator.custom_tools."
+            ) from e
+
+
+def load_overseer_custom_tools(config: MapleConfig):
+    """Load and register custom MCP tools for the Overseer.
+
+    Args:
+        config: Loaded MapleConfig.
+    """
+    if not config.overseer.custom_tools:
+        return
+
+    from maple.overseer.server import mcp
+
+    for tool_path in config.overseer.custom_tools:
+        try:
+            func = import_string(tool_path)
+            if not hasattr(func, "__mcp_tool__"):
+                mcp.tool(func)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to load custom tool '{tool_path}': {e}. "
+                f"Check the path in maple.config.yaml under overseer.custom_tools."
+            ) from e

maple/hooks.py

@@ -0,0 +1,37 @@
+"""Agent event hooks for MAPLE provenance capture."""
+
+import os
+import requests
+
+
+class ReasoningCaptureHook:
+    """Captures LLM reasoning text and logs to MADSci Event Manager.
+    
+    Intercepts text tokens between tool calls, buffers them,
+    and flushes to the Event Manager when a tool is invoked.
+    """
+
+    def __init__(self, mcp_base_url: str = None):
+        self.mcp_base_url = mcp_base_url or os.getenv("MCP_EXECUTOR_URL", "http://localhost:8102")
+        self._buffer = ""
+
+    def accumulate(self, text: str):
+        """Add text to the reasoning buffer."""
+        self._buffer += text
+
+    def flush(self, tool_name: str):
+        """Flush buffered reasoning to the MCP server's log endpoint."""
+        if not self._buffer.strip():
+            return
+        try:
+            requests.post(
+                f"{self.mcp_base_url}/log_reasoning",
+                json={
+                    "reasoning": self._buffer.strip(),
+                    "before_tool": tool_name,
+                },
+                timeout=5,
+            )
+        except Exception:
+            pass
+        self._buffer = ""

maple/middleware.py

@@ -0,0 +1,42 @@
+"""MAPLE MCP middleware — extracts identity from Authorization header."""
+
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+from fastmcp.exceptions import ToolError
+
+from maple.auth import is_valid_token
+
+
+class AuthMiddleware(Middleware):
+    """Extracts bearer token from Authorization header and stashes in context.
+    
+    Every tool call passes through this middleware. The token is made
+    available to tools via `await ctx.get_state("maple_identity")`.
+    
+    Rejects requests with missing or malformed tokens.
+    """
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        headers = get_http_headers(include={"authorization"})
+        authorization = headers.get("authorization", "")
+
+        scheme, _, token = authorization.partition(" ")
+        token = token.strip()
+
+        if scheme.lower() != "bearer" or not token:
+            raise ToolError(
+                "Authorization required. Include 'Authorization: Bearer <token>' header. "
+                "Run 'maple chat' to auto-generate credentials."
+            )
+
+        if not is_valid_token(token):
+            raise ToolError(
+                "Invalid token format. Expected a UUIDv4 string. "
+                "Delete ~/.maple/credentials and retry to regenerate."
+            )
+
+        if context.fastmcp_context is None:
+            raise ToolError("Request context unavailable")
+
+        await context.fastmcp_context.set_state("maple_identity", token)
+        return await call_next(context)