switchplane 0.1.0__py3-none-any.whl

switchplane/app.py

@@ -0,0 +1,157 @@
+"""Application and MCP server configuration."""
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from switchplane.agent import AgentSpec
+    from switchplane.config import AppConfig
+
+_VALID_APP_NAME = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+
+
+class OAuthConfig(BaseModel):
+    """OAuth 2.0 configuration for an MCP server.
+
+    Two modes are supported:
+
+    **MCP-spec OAuth** (default): Leave ``auth_url`` and ``token_url``
+    unset.  The MCP SDK's ``OAuthClientProvider`` discovers endpoints
+    from the MCP server's protected-resource metadata automatically.
+
+    **Direct OIDC**: Set ``auth_url`` and ``token_url`` to point at an
+    external identity provider (e.g. Keycloak/QuantumK).  Switchplane
+    runs the PKCE authorization-code flow against those endpoints
+    directly, bypassing MCP metadata discovery.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    client_id: str
+    client_secret: str | None = None
+    callback_port: int = 3118
+    scopes: str | None = None
+    auth_url: str | None = None
+    token_url: str | None = None
+
+    @property
+    def is_direct(self) -> bool:
+        """True when explicit OIDC endpoints are configured."""
+        return self.auth_url is not None and self.token_url is not None
+
+    def model_post_init(self, __context) -> None:
+        if bool(self.auth_url) != bool(self.token_url):
+            raise ValueError("Provide both 'auth_url' and 'token_url', or neither")
+
+
+class McpServerConfig(BaseModel):
+    """Configuration for an MCP server.
+
+    Provide `command` for stdio transport (Switchplane manages the process)
+    or `url` for HTTP transport (Switchplane connects to an existing server).
+    """
+
+    model_config = ConfigDict(
+        str_strip_whitespace=True,
+        validate_assignment=True,
+    )
+
+    name: str
+    command: list[str] | None = None
+    url: str | None = None
+    env: dict[str, str] = {}
+    http_transport: str | None = None
+    oauth: OAuthConfig | None = None
+    oauth_group: str | None = None
+    timeout: float | None = 30.0
+
+    @property
+    def oauth_storage_key(self) -> str:
+        """Key for OAuth token storage. Servers sharing an oauth_group share tokens."""
+        return self.oauth_group or self.name
+
+    @property
+    def transport(self) -> str:
+        return "stdio" if self.command else "http"
+
+    def model_post_init(self, __context) -> None:
+        if self.command and self.url:
+            raise ValueError("Provide either 'command' (stdio) or 'url' (http), not both")
+        if not self.command and not self.url:
+            raise ValueError("Provide either 'command' (stdio) or 'url' (http)")
+        if self.oauth and self.http_transport:
+            raise ValueError("Provide either 'oauth' or 'http_transport', not both")
+        if self.oauth and not self.url:
+            raise ValueError("OAuth requires HTTP transport ('url' must be set)")
+
+
+class Application:
+    """Application container for agents and MCP servers."""
+
+    def __init__(
+        self,
+        name: str,
+        runtime_dir: str | Path | None = None,
+        default_config: Path | None = None,
+        config_class: "type[AppConfig] | None" = None,
+    ) -> None:
+        """Initialize application.
+
+        Args:
+            name: Application name
+            runtime_dir: Optional runtime directory path (defaults to ~/.{name})
+            default_config: Optional path to default config file bundled with the app
+            config_class: Pydantic model class used to parse the merged config.
+                Defaults to AppConfig; pass a subclass to support app-specific
+                config sections that are otherwise dropped by the base model.
+        """
+        from switchplane.config import AppConfig as _AppConfig
+
+        if not _VALID_APP_NAME.match(name):
+            raise ValueError(
+                f"Invalid application name {name!r}. "
+                "Names must start with a letter and contain only letters, digits, hyphens, or underscores."
+            )
+        self.name = name
+        self.runtime_dir = Path(runtime_dir).expanduser() if runtime_dir else Path.home() / f".{name}"
+        self.default_config_path = default_config
+        self.config_class: type[AppConfig] = config_class or _AppConfig
+        self.agents: dict[str, AgentSpec] = {}
+        self.mcp_servers: dict[str, McpServerConfig] = {}
+        self._discovery_roots: list[str] = []
+
+    def discover_agents(self, root: str) -> None:
+        """Store root directory for later agent discovery.
+
+        Args:
+            root: Root directory path to discover agents from
+        """
+        self._discovery_roots.append(root)
+
+    def register_agent(self, spec: "AgentSpec") -> None:
+        """Register an agent specification.
+
+        Args:
+            spec: Agent specification to register
+        """
+        self.agents[spec.agent_name] = spec
+
+    def register_mcp_server(self, config: McpServerConfig) -> None:
+        """Register an MCP server configuration.
+
+        Args:
+            config: MCP server configuration to register
+        """
+        self.mcp_servers[config.name] = config
+
+    def run(self) -> None:
+        """Discover agents and start the CLI."""
+        from switchplane.cli import build_cli
+        from switchplane.discovery import discover_agents_for_app
+
+        discover_agents_for_app(self)
+        cli = build_cli(self)
+        cli()

switchplane/checkpoint.py

@@ -0,0 +1,365 @@
+"""Custom LangGraph checkpoint saver backed by SQLite."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+import aiosqlite
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    JsonPlusSerializer,
+)
+
+
+async def setup_tables(db: aiosqlite.Connection) -> None:
+    """Create checkpoint tables in the SQLite database."""
+    await db.execute("""
+        CREATE TABLE IF NOT EXISTS checkpoints (
+            thread_id TEXT NOT NULL,
+            checkpoint_ns TEXT NOT NULL DEFAULT '',
+            checkpoint_id TEXT NOT NULL,
+            parent_checkpoint_id TEXT,
+            type TEXT,
+            checkpoint BLOB,
+            metadata BLOB,
+            metadata_type TEXT,
+            PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+        )
+    """)
+
+    await db.execute("""
+        CREATE TABLE IF NOT EXISTS checkpoint_writes (
+            thread_id TEXT NOT NULL,
+            checkpoint_ns TEXT NOT NULL DEFAULT '',
+            checkpoint_id TEXT NOT NULL,
+            task_id TEXT NOT NULL,
+            idx INTEGER NOT NULL,
+            channel TEXT NOT NULL,
+            type TEXT,
+            blob BLOB,
+            PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+        )
+    """)
+
+    await db.commit()
+
+
+class SqliteCheckpointSaver(BaseCheckpointSaver):
+    """LangGraph checkpoint saver backed by SQLite."""
+
+    serde = JsonPlusSerializer()
+
+    def __init__(self, db: aiosqlite.Connection):
+        """Initialize with an existing SQLite connection."""
+        super().__init__()
+        self.db = db
+
+    async def setup(self) -> None:
+        """Create checkpoint tables if they don't exist."""
+        await setup_tables(self.db)
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple for the given config."""
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = config["configurable"].get("checkpoint_id")
+
+        # Query for the checkpoint
+        if checkpoint_id:
+            # Get specific checkpoint
+            cursor = await self.db.execute(
+                """
+                SELECT checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata, metadata_type
+                FROM checkpoints
+                WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+            """,
+                (thread_id, checkpoint_ns, checkpoint_id),
+            )
+        else:
+            # Get latest checkpoint
+            cursor = await self.db.execute(
+                """
+                SELECT checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata, metadata_type
+                FROM checkpoints
+                WHERE thread_id = ? AND checkpoint_ns = ?
+                ORDER BY checkpoint_id DESC
+                LIMIT 1
+            """,
+                (thread_id, checkpoint_ns),
+            )
+
+        row = await cursor.fetchone()
+        if not row:
+            return None
+
+        checkpoint_id, parent_checkpoint_id, checkpoint_type, checkpoint_blob, metadata_blob, metadata_type = row
+
+        # Deserialize checkpoint and metadata
+        checkpoint = self.serde.loads_typed((checkpoint_type, checkpoint_blob)) if checkpoint_blob else {}
+        metadata = self.serde.loads_typed((metadata_type or checkpoint_type, metadata_blob)) if metadata_blob else {}
+
+        # Query for pending writes
+        writes_cursor = await self.db.execute(
+            """
+            SELECT task_id, channel, type, blob
+            FROM checkpoint_writes
+            WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+            ORDER BY task_id, idx
+        """,
+            (thread_id, checkpoint_ns, checkpoint_id),
+        )
+
+        writes_rows = await writes_cursor.fetchall()
+        pending_writes = []
+        for write_row in writes_rows:
+            task_id, channel, write_type, write_blob = write_row
+            value = self.serde.loads_typed((write_type, write_blob)) if write_blob else None
+            pending_writes.append((task_id, channel, value))
+
+        # Build parent config if there's a parent checkpoint
+        parent_config = None
+        if parent_checkpoint_id:
+            parent_config = {
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": checkpoint_ns,
+                    "checkpoint_id": parent_checkpoint_id,
+                }
+            }
+
+        return CheckpointTuple(
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": checkpoint_ns,
+                    "checkpoint_id": checkpoint_id,
+                }
+            },
+            checkpoint=checkpoint,
+            metadata=metadata,
+            parent_config=parent_config,
+            pending_writes=pending_writes,
+        )
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int = 10,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """List checkpoints for a thread."""
+        if config is None:
+            return
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+
+        # Build query
+        query = """
+            SELECT checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata, metadata_type
+            FROM checkpoints
+            WHERE thread_id = ? AND checkpoint_ns = ?
+        """
+        params = [thread_id, checkpoint_ns]
+
+        # Add before filter if specified
+        if before:
+            before_checkpoint_id = before["configurable"].get("checkpoint_id")
+            if before_checkpoint_id:
+                query += " AND checkpoint_id < ?"
+                params.append(before_checkpoint_id)
+
+        query += " ORDER BY checkpoint_id DESC LIMIT ?"
+        params.append(limit)
+
+        cursor = await self.db.execute(query, params)
+        rows = await cursor.fetchall()
+
+        for row in rows:
+            checkpoint_id, parent_checkpoint_id, checkpoint_type, checkpoint_blob, metadata_blob, metadata_type = row
+
+            # Deserialize
+            checkpoint = self.serde.loads_typed((checkpoint_type, checkpoint_blob)) if checkpoint_blob else {}
+            metadata = (
+                self.serde.loads_typed((metadata_type or checkpoint_type, metadata_blob)) if metadata_blob else {}
+            )
+
+            # Apply filter if provided
+            if filter and not all(metadata.get(k) == v for k, v in filter.items()):
+                continue
+
+            # Query for pending writes
+            writes_cursor = await self.db.execute(
+                """
+                SELECT task_id, channel, type, blob
+                FROM checkpoint_writes
+                WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+                ORDER BY task_id, idx
+            """,
+                (thread_id, checkpoint_ns, checkpoint_id),
+            )
+
+            writes_rows = await writes_cursor.fetchall()
+            pending_writes = []
+            for write_row in writes_rows:
+                task_id, channel, write_type, write_blob = write_row
+                value = self.serde.loads_typed((write_type, write_blob)) if write_blob else None
+                pending_writes.append((task_id, channel, value))
+
+            # Build parent config
+            parent_config = None
+            if parent_checkpoint_id:
+                parent_config = {
+                    "configurable": {
+                        "thread_id": thread_id,
+                        "checkpoint_ns": checkpoint_ns,
+                        "checkpoint_id": parent_checkpoint_id,
+                    }
+                }
+
+            yield CheckpointTuple(
+                config={
+                    "configurable": {
+                        "thread_id": thread_id,
+                        "checkpoint_ns": checkpoint_ns,
+                        "checkpoint_id": checkpoint_id,
+                    }
+                },
+                checkpoint=checkpoint,
+                metadata=metadata,
+                parent_config=parent_config,
+                pending_writes=pending_writes,
+            )
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint."""
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        parent_checkpoint_id = config["configurable"].get("checkpoint_id")
+
+        # Generate new checkpoint ID from checkpoint data
+        checkpoint_id = checkpoint["id"]
+
+        # Serialize checkpoint and metadata
+        checkpoint_type, checkpoint_blob = self.serde.dumps_typed(checkpoint)
+        metadata_type, metadata_blob = self.serde.dumps_typed(metadata)
+
+        # Insert or replace checkpoint
+        await self.db.execute(
+            """
+            INSERT OR REPLACE INTO checkpoints
+            (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata, metadata_type)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+            (
+                thread_id,
+                checkpoint_ns,
+                checkpoint_id,
+                parent_checkpoint_id,
+                checkpoint_type,
+                checkpoint_blob,
+                metadata_blob,
+                metadata_type,
+            ),
+        )
+
+        await self.db.commit()
+
+        # Return updated config with new checkpoint_id
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint_id,
+            }
+        }
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: list[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Save pending writes for a checkpoint."""
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = config["configurable"]["checkpoint_id"]
+
+        # Insert writes
+        rows = []
+        for idx, (channel, value) in enumerate(writes):
+            write_type, write_blob = self.serde.dumps_typed(value)
+            rows.append(
+                (
+                    thread_id,
+                    checkpoint_ns,
+                    checkpoint_id,
+                    task_id,
+                    idx,
+                    channel,
+                    write_type,
+                    write_blob,
+                )
+            )
+
+        await self.db.executemany(
+            """
+            INSERT OR REPLACE INTO checkpoint_writes
+            (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, blob)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+            rows,
+        )
+
+        await self.db.commit()
+
+    # Sync methods - not implemented
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Sync version not implemented - use async version."""
+        raise NotImplementedError("Use async version: aget_tuple")
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int = 10,
+    ):
+        """Sync version not implemented - use async version."""
+        raise NotImplementedError("Use async version: alist")
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Sync version not implemented - use async version."""
+        raise NotImplementedError("Use async version: aput")
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: list[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Sync version not implemented - use async version."""
+        raise NotImplementedError("Use async version: aput_writes")