mithai 0.12.0__py3-none-any.whl

mithai/__init__.py

@@ -0,0 +1,49 @@
+"""mithai — AI agent framework for organizations."""
+
+import platform
+import sys
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+try:
+    __version__ = _pkg_version("mithai")
+except Exception:
+    __version__ = "0.0.0-dev"
+
+
+def _platform_tag() -> str:
+    """Return a platform tag like 'darwin-arm64'."""
+    system = platform.system().lower()
+    arch = platform.machine()
+    if arch == "x86_64":
+        arch = "amd64"
+    return f"{system}-{arch}"
+
+
+def get_version_string() -> str:
+    """Return version string with platform info."""
+    return f"{__version__} ({_platform_tag()})"
+
+
+def get_bundled_path() -> Path:
+    """Return the base path for bundled data files.
+
+    When running from a PyInstaller binary, data files are extracted
+    to sys._MEIPASS. When running from source, use the repo root. When
+    installed from a wheel, bundled skills live under the mithai package.
+    """
+    if getattr(sys, "_MEIPASS", None):
+        return Path(sys._MEIPASS)
+
+    package_dir = Path(__file__).resolve().parent
+
+    # Wheel install: pyproject force-includes top-level skills as mithai/skills.
+    if (package_dir / "skills").exists():
+        return package_dir
+
+    # Source checkout: repo root is two levels up from src/mithai/.
+    source_root = package_dir.parent.parent
+    if (source_root / "skills").exists():
+        return source_root
+
+    return package_dir

mithai/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running mithai as: python -m mithai"""
+
+from mithai.cli.main import cli
+
+cli()

mithai/adapters/api.py

@@ -0,0 +1,39 @@
+"""Headless API adapter — process stays alive while /api/trigger handles all input."""
+
+import logging
+import threading
+
+from mithai.adapters.base import Adapter, MessageHandler, OutgoingMessage
+from mithai.human.mcp import HumanRequest
+
+logger = logging.getLogger(__name__)
+
+
+class APIAdapter(Adapter):
+    """Blocks forever so the embedded API server (MITHAI_UI_PORT) can serve all traffic.
+
+    No stdin, no Slack connection required. Responses are logged at INFO level.
+    Human approval requests are auto-denied (no interactive terminal).
+    """
+
+    def __init__(self):
+        self._stop_event = threading.Event()
+
+    def start(self, on_message: MessageHandler, on_channel_join=None,
+              on_observe=None, on_bot_reply=None) -> None:
+        self._stop_event.wait()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+    def send(self, message: OutgoingMessage) -> None:
+        text = message.text
+        preview = text[:200] + ("…" if len(text) > 200 else "")
+        logger.info("[api] → %s", preview)
+
+    def request_human_approval(self, request: HumanRequest, channel_id: str) -> bool:
+        logger.warning(
+            "api adapter: auto-denying approval for '%s' (no interactive terminal)",
+            request.tool_name,
+        )
+        return False

mithai/adapters/base.py

@@ -0,0 +1,135 @@
+"""Abstract messaging adapter interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Callable, Optional
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from mithai.human.mcp import HumanRequest
+
+# Callback type: (message, adapter) -> response text
+MessageHandler = Callable[["IncomingMessage", "Adapter"], str]
+
+# Callback type: (channel_id, channel_name) -> response text to post (or None)
+ChannelJoinHandler = Callable[[str, str], Optional[str]]
+
+# Callback type: (message,) -> None  — called for observed messages (no reply)
+ChannelObserveHandler = Callable[["IncomingMessage"], None]
+
+# Callback type: (channel_id, user_id, text, message_id) -> None — log bot reply to channel_context
+BotReplyHandler = Callable[[str, str, str, str], None]
+
+
+@dataclass
+class ImageAttachment:
+    """A base64-encoded image attached to a message."""
+    data: str          # base64-encoded bytes
+    media_type: str    # e.g. "image/png", "image/jpeg"
+
+
+@dataclass
+class IncomingMessage:
+    """Platform-agnostic incoming message."""
+
+    text: str
+    channel_id: str
+    user_id: str
+    platform: str = ""
+    message_id: str = field(default_factory=lambda: uuid4().hex[:12])
+    thread_id: str | None = None  # Slack thread_ts, etc.
+    images: list[ImageAttachment] = field(default_factory=list)
+    non_image_files: list[str] = field(default_factory=list)  # filenames of skipped non-image attachments
+    extra_system_prompt: str = ""  # schedule-specific instructions, appended to system prompt for this turn only
+
+
+@dataclass
+class OutgoingMessage:
+    """Platform-agnostic response to send."""
+
+    text: str
+    channel_id: str
+
+
+class Adapter(ABC):
+    """
+    Abstract messaging adapter.
+
+    Each platform (Slack, Telegram, CLI) implements this.
+    Adapters handle receiving messages, sending responses,
+    and presenting Human MCP requests.
+    """
+
+    @abstractmethod
+    def start(self, on_message: MessageHandler, on_channel_join: "ChannelJoinHandler | None" = None,
+              on_observe: "ChannelObserveHandler | None" = None,
+              on_bot_reply: "BotReplyHandler | None" = None) -> None:
+        """
+        Start listening for messages.
+
+        on_message(message, adapter) is called for each incoming message.
+        The adapter passes itself so the engine can route Human MCP
+        approvals back through the correct platform.
+
+        on_bot_reply is called after the bot sends a reply (used by Slack
+        adapters to log outgoing messages to channel context).
+        """
+        ...
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Clean shutdown."""
+        ...
+
+    @abstractmethod
+    def send(self, message: OutgoingMessage) -> None:
+        """Send a message to the platform."""
+        ...
+
+    @abstractmethod
+    def request_human_approval(self, request: HumanRequest, channel_id: str) -> bool:
+        """
+        Present a Human MCP request and wait for response.
+
+        For "approve": show action details, wait for yes/no.
+        For "confirm": show action details, wait for confirmation text.
+
+        Returns True if approved, False if denied or timed out.
+        """
+        ...
+
+    # ── Optional status callbacks (no-op by default) ──
+    # Engine calls these to let the adapter show progress feedback.
+
+    def on_thinking_start(self) -> None:
+        """Called before an LLM call starts."""
+
+    def on_thinking_end(self, elapsed_s: float) -> None:
+        """Called when an LLM call completes."""
+
+    def on_tool_start(self, tool_name: str, tool_input: dict) -> None:
+        """Called before a tool is executed."""
+
+    def before_tool_call(self, tool_name: str, tool_input: dict) -> str | None:
+        """Return a synthetic tool result to skip execution, or None to continue."""
+        return None
+
+    def on_tool_end(self, tool_name: str, elapsed_s: float, approved: bool) -> None:
+        """Called after a tool finishes executing."""
+
+    def on_tool_result(self, tool_name: str, tool_input: dict, result: str) -> None:
+        """Called after a tool returns a result."""
+
+    def on_synthesizing(self) -> None:
+        """Called before the follow-up LLM call after tool results."""
+
+    def fetch_thread_context(self, channel_id: str, thread_ts: str) -> list[str] | None:
+        """Fetch historical messages from a thread for backfill context.
+
+        Called when the agent is @mentioned in a thread for the first time and
+        needs to see what was discussed above. Returns formatted 'name: text'
+        lines oldest-first, or None if not supported by this adapter.
+        """
+        return None

mithai/adapters/cli.py

@@ -0,0 +1,465 @@
+"""CLI/terminal adapter for local development and testing."""
+
+import json
+import sys
+import time
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.formatted_text import ANSI
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+from mithai.adapters.base import Adapter, IncomingMessage, MessageHandler, OutgoingMessage
+from mithai.adapters.formatters import CLIFormatter
+from mithai.human.mcp import HumanRequest
+
+_console = Console()
+
+# Slash commands with descriptions for autocomplete
+_SLASH_COMMANDS = {
+    "/help": "Show available commands",
+    "/skills": "List loaded skills and tool counts",
+    "/sessions": "List recent conversation sessions",
+    "/memory": "Show memory files",
+    "/clear": "Clear the terminal screen",
+    "/status": "Show engine status",
+}
+
+
+class _SlashCompleter(Completer):
+    """Tab-complete slash commands when input starts with '/'."""
+
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor
+        if not text.startswith("/"):
+            return
+        for cmd, desc in _SLASH_COMMANDS.items():
+            if cmd.startswith(text):
+                yield Completion(cmd, start_position=-len(text), display_meta=desc)
+
+
+# ── In-chat slash commands ──
+
+def _handle_slash_command(text: str, engine=None) -> str | None:
+    """Handle in-chat slash commands. Returns response text or None if not a command."""
+    cmd = text.strip().lower()
+    parts = cmd.split(None, 1)
+    command = parts[0]
+
+    if command == "/help":
+        return (
+            "**Chat commands:**\n"
+            "| Command | Description |\n"
+            "|---------|-------------|\n"
+            "| `/help` | Show this help |\n"
+            "| `/skills` | List loaded skills and tool counts |\n"
+            "| `/sessions` | List recent conversation sessions |\n"
+            "| `/memory` | Show memory files |\n"
+            "| `/clear` | Clear the screen |\n"
+            "| `/status` | Show engine status |\n"
+            "| `quit` | Exit the chat |"
+        )
+
+    if command == "/skills" and engine:
+        lines = ["**Loaded skills:**\n"]
+        for name, skill in sorted(engine._skills.items()):
+            tool_count = len(skill.tools)
+            mcp_count = sum(
+                len(e.get("tools", [])) if isinstance(e.get("tools"), list) else 0
+                for e in skill.mcp_tools
+            )
+            has_wildcard = any(e.get("tools") == "*" for e in skill.mcp_tools)
+            label = f"{tool_count} tools"
+            if mcp_count:
+                label += f" + {mcp_count} MCP"
+            if has_wildcard:
+                label += " + MCP(*)"
+            lines.append(f"- **{name}** — {label}")
+        return "\n".join(lines)
+
+    if command == "/sessions" and engine:
+        sessions = engine._sessions.list_sessions(limit=10)
+        if not sessions:
+            return "*No sessions yet.*"
+        lines = ["**Recent sessions:**\n"]
+        for s in sessions:
+            ts = s["updated_at"][:16].replace("T", " ") if s.get("updated_at") else "?"
+            preview = s.get("last_message", "")[:60]
+            lines.append(f"- `{s['session_id']}` ({s['turn_count']} turns, {ts}) — {preview}")
+        return "\n".join(lines)
+
+    if command == "/memory" and engine and engine._memory:
+        files = engine._memory.list("**/*")
+        if not files:
+            return "*No memory files.*"
+        lines = ["**Memory files:**\n"]
+        for f in sorted(files):
+            lines.append(f"- `{f}`")
+        return "\n".join(lines)
+
+    if command == "/clear":
+        _console.clear()
+        return None  # No output, just clear
+
+    if command == "/status" and engine:
+        parts_list = []
+        parts_list.append(f"**Agent:** {engine._agent_id or 'default'}")
+        parts_list.append(f"**Skills:** {len(engine._skills)} loaded")
+        if engine._mcp_manager:
+            servers = list(engine._mcp_manager._configs.keys())
+            connected = [
+                name for name, entry in engine._mcp_manager._sessions.items()
+            ]
+            parts_list.append(f"**MCP servers:** {', '.join(servers) if servers else 'none'}")
+            if connected:
+                parts_list.append(f"**MCP connected:** {', '.join(connected)}")
+        if engine._memory:
+            parts_list.append("**Memory:** active")
+        llm_model = engine._llm_config.get("model", "?")
+        parts_list.append(f"**LLM:** {engine._llm_config.get('provider', '?')} / {llm_model}")
+        return "\n".join(parts_list)
+
+    return None  # Not a recognized command
+
+
+def _flush_stdin():
+    """Discard any buffered stdin input (keystrokes during LLM processing).
+
+    When the LLM takes seconds to respond, users may press Enter or type
+    while waiting.  Those keystrokes accumulate in the terminal buffer and
+    would be read as empty prompts (you> you> you> ...) or auto-deny
+    approval prompts.  Flushing clears that buffer.
+    """
+    try:
+        import termios
+        termios.tcflush(sys.stdin.fileno(), termios.TCIFLUSH)
+    except (ImportError, termios.error, ValueError, OSError):
+        # Windows or non-tty — best-effort: drain anything readable
+        try:
+            import select
+            while select.select([sys.stdin], [], [], 0)[0]:
+                sys.stdin.readline()
+        except Exception:
+            pass
+
+
+class CLIAdapter(Adapter):
+    """
+    Interactive terminal REPL, with piped-stdin support.
+
+    When stdin is a TTY the adapter runs an interactive REPL.
+    When stdin is piped (e.g. ``echo "msg" | mithai run``) it reads one
+    message, runs the full conversation loop, writes the final plain-text
+    response to stdout, and exits.
+    """
+
+    _SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def __init__(self):
+        self._running = False
+        self._engine = None
+        self._formatter = CLIFormatter()
+        self._thinking_start: float | None = None
+        self._live: Live | None = None
+        self._piped = not sys.stdin.isatty()
+        if not self._piped:
+            self._prompt_session = PromptSession(
+                completer=_SlashCompleter(),
+                complete_while_typing=True,
+            )
+
+    def set_engine(self, engine) -> None:
+        """Give the adapter a reference to the engine for slash commands."""
+        self._engine = engine
+
+    def start(self, on_message: MessageHandler, on_channel_join=None, on_observe=None,
+              on_bot_reply=None) -> None:
+        if self._piped:
+            self._start_piped(on_message)
+        else:
+            self._start_interactive(on_message)
+
+    def _start_piped(self, on_message: MessageHandler) -> None:
+        """Read one message from stdin, process through the full conversation loop,
+        write the final plain-text response to stdout, and exit.
+
+        Stdin may be plain text or a JSON object. JSON form:
+            {"text": "...", "system_prompt_append": "...", "channel_id": "..."}
+        Unknown keys are ignored. Plain text is used as-is.
+        """
+        raw = sys.stdin.read().strip()
+        if not raw:
+            return
+
+        text = raw
+        extra_system_prompt = ""
+        channel_id = "cli"
+        try:
+            data = json.loads(raw)
+            if isinstance(data, dict):
+                text = data.get("text", raw)
+                extra_system_prompt = data.get("system_prompt_append", "")
+                channel_id = data.get("channel_id", "cli")
+        except (ValueError, TypeError):
+            pass  # not JSON — treat as plain text
+
+        message = IncomingMessage(
+            text=text,
+            channel_id=channel_id,
+            user_id="local",
+            platform="cli",
+            extra_system_prompt=extra_system_prompt,
+        )
+
+        try:
+            response = on_message(message, self)
+        except Exception as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            raise SystemExit(1) from exc
+
+        if response:
+            print(response, flush=True)
+
+    def _start_interactive(self, on_message: MessageHandler) -> None:
+        """Run the interactive REPL (original behavior)."""
+        self._running = True
+        _console.print(
+            "\n  [bright_magenta bold]mithai[/] [muted]ready · type [white]quit[/white] to exit · [white]/help[/white] for commands[/]\n"
+        )
+
+        # Build ANSI prompt using Rich's rendering
+        prompt_ansi = ANSI("\x1b[1;96myou>\x1b[0m ")
+
+        while self._running:
+            try:
+                text = self._prompt_session.prompt(prompt_ansi).strip()
+            except (EOFError, KeyboardInterrupt):
+                _console.print()
+                break
+
+            if not text:
+                continue
+            if text.lower() in ("quit", "exit", "q"):
+                break
+
+            # Handle in-chat slash commands
+            if text.startswith("/"):
+                result = _handle_slash_command(text, engine=self._engine)
+                if result:
+                    _console.print()
+                    try:
+                        _console.print(Panel(
+                            Markdown(result),
+                            title="[bright_magenta]mithai[/]",
+                            border_style="bright_magenta",
+                            padding=(1, 2),
+                        ))
+                    except Exception:
+                        _console.print(result)
+                    _console.print()
+                continue
+
+            message = IncomingMessage(
+                text=text,
+                channel_id="cli",
+                user_id="local",
+                platform="cli",
+            )
+
+            response = on_message(message, self)
+
+            # Flush any keystrokes buffered while the LLM was processing
+            _flush_stdin()
+
+            _console.print()
+            for chunk in self._formatter.format(response):
+                try:
+                    md = Markdown(chunk)
+                    _console.print(Panel(
+                        md,
+                        title="[bright_magenta]mithai[/]",
+                        border_style="bright_magenta",
+                        padding=(1, 2),
+                    ))
+                except Exception:
+                    _console.print(f"[bright_magenta]mithai>[/] {chunk}")
+            _console.print()
+
+    def stop(self) -> None:
+        self._running = False
+
+    def send(self, message: OutgoingMessage) -> None:
+        if self._piped:
+            # In piped mode, write plain text to stdout (no Rich formatting)
+            print(message.text, flush=True)
+            return
+        for chunk in self._formatter.format(message.text):
+            try:
+                md = Markdown(chunk)
+                _console.print(Panel(
+                    md,
+                    title="[bright_magenta]mithai[/]",
+                    border_style="bright_magenta",
+                    padding=(1, 2),
+                ))
+            except Exception:
+                _console.print(f"[bright_magenta]mithai>[/] {chunk}")
+
+    def request_human_approval(self, request: HumanRequest, channel_id: str) -> bool:
+        if self._piped:
+            print(
+                f"Error: tool '{request.tool_name}' requires human approval "
+                "but stdin is not a terminal — auto-denying.",
+                file=sys.stderr,
+            )
+            return False
+        # Stop any active spinner before showing approval dialog
+        self._stop_live()
+        # Flush buffered keystrokes so stale Enter presses don't auto-deny
+        _flush_stdin()
+
+        _console.print()
+        level_color = "yellow" if request.level == "approve" else "red"
+        _console.print(Panel(
+            request.description,
+            title=f"[{level_color} bold]Human Approval Required [{request.level.upper()}][/]",
+            border_style=level_color,
+            padding=(1, 2),
+        ))
+
+        if request.level == "confirm":
+            confirm_text = _extract_confirm_token(request)
+            _console.print(
+                f"  Type [bold]{confirm_text}[/] to confirm, or anything else to deny:"
+            )
+            try:
+                answer = _console.input("  [yellow]>[/] ").strip()
+            except (EOFError, KeyboardInterrupt):
+                _console.print("  [red]Denied.[/]")
+                return False
+            approved = answer == confirm_text
+        else:
+            try:
+                answer = _console.input("  [yellow]Approve? [y/N]:[/] ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                _console.print("  [red]Denied.[/]")
+                return False
+            approved = answer in ("y", "yes")
+
+        if approved:
+            _console.print("  [green]Approved.[/]\n")
+        else:
+            _console.print("  [red]Denied.[/]\n")
+        return approved
+
+
+    # ── Status callbacks for progress feedback ──
+
+    def on_thinking_start(self) -> None:
+        if self._piped:
+            return
+        self._thinking_start = time.monotonic()
+        self._live = Live(
+            Text("  ● thinking...", style="bright_magenta"),
+            console=_console,
+            refresh_per_second=4,
+            transient=True,
+        )
+        self._live.start()
+        self._spin_thread_running = True
+        import threading
+        self._spin_thread = threading.Thread(target=self._spin_loop, daemon=True)
+        self._spin_thread.start()
+
+    def _spin_loop(self) -> None:
+        """Update the spinner with elapsed time."""
+        idx = 0
+        while self._spin_thread_running and self._live:
+            elapsed = time.monotonic() - (self._thinking_start or time.monotonic())
+            frame = self._SPINNER_FRAMES[idx % len(self._SPINNER_FRAMES)]
+            try:
+                self._live.update(
+                    Text(f"  {frame} thinking... {elapsed:.0f}s", style="bright_magenta")
+                )
+            except Exception:
+                break
+            idx += 1
+            time.sleep(0.15)
+
+    def _stop_live(self) -> None:
+        """Stop the live spinner."""
+        self._spin_thread_running = False
+        if self._live:
+            try:
+                self._live.stop()
+            except Exception:
+                pass
+            self._live = None
+
+    def on_thinking_end(self, elapsed_s: float) -> None:
+        self._stop_live()
+
+    def on_tool_start(self, tool_name: str, tool_input: dict) -> None:
+        if self._piped:
+            return
+        self._stop_live()
+        # Show a compact preview of what's being called
+        preview = ""
+        if "command" in tool_input:
+            preview = f" `{tool_input['command'][:60]}`"
+        elif "repo" in tool_input:
+            preview = f" {tool_input['repo']}"
+        elif "namespace" in tool_input:
+            preview = f" ns={tool_input['namespace']}"
+        _console.print(f"  [cyan]▸[/] [dim]tool:[/] {tool_name}{preview}")
+        self._thinking_start = time.monotonic()
+
+    def on_tool_end(self, tool_name: str, elapsed_s: float, approved: bool) -> None:
+        if self._piped:
+            return
+        if approved:
+            _console.print(f"  [green]✓[/] [dim]{tool_name}[/] [muted]({elapsed_s:.1f}s)[/]")
+        else:
+            _console.print(f"  [red]✗[/] [dim]{tool_name} denied[/]")
+
+    def on_synthesizing(self) -> None:
+        if self._piped:
+            return
+        self._thinking_start = time.monotonic()
+        self._live = Live(
+            Text("  ● synthesizing response...", style="bright_magenta"),
+            console=_console,
+            refresh_per_second=4,
+            transient=True,
+        )
+        self._live.start()
+        self._spin_thread_running = True
+        import threading
+        self._spin_thread = threading.Thread(target=self._synth_spin_loop, daemon=True)
+        self._spin_thread.start()
+
+    def _synth_spin_loop(self) -> None:
+        idx = 0
+        while self._spin_thread_running and self._live:
+            elapsed = time.monotonic() - (self._thinking_start or time.monotonic())
+            frame = self._SPINNER_FRAMES[idx % len(self._SPINNER_FRAMES)]
+            try:
+                self._live.update(
+                    Text(f"  {frame} synthesizing response... {elapsed:.0f}s", style="bright_magenta")
+                )
+            except Exception:
+                break
+            idx += 1
+            time.sleep(0.15)
+
+
+def _extract_confirm_token(request: HumanRequest) -> str:
+    """Extract a confirmation token from tool input for the confirm level."""
+    for value in request.tool_input.values():
+        if isinstance(value, str) and value:
+            return value
+    return request.tool_name.split("__")[-1]