krons 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

krons/__init__.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy module re-exports via __getattr__
+_MODULE_ALIASES: dict[str, str] = {
+    "types": "krons.core.types",
+    "specs": "krons.core.specs",
+    "session": "krons.session",
+    "operations": "krons.work.operations",
+    "agent": "krons.agent",
+    "resource": "krons.resource",
+    "work": "krons.work",
+}
+
+_LOADED_MODULES: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy load aliased modules."""
+    if name in _LOADED_MODULES:
+        return _LOADED_MODULES[name]
+
+    if name in _MODULE_ALIASES:
+        from importlib import import_module
+
+        module = import_module(_MODULE_ALIASES[name])
+        _LOADED_MODULES[name] = module
+        return module
+
+    raise AttributeError(f"module 'krons' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """List available attributes."""
+    return list(_MODULE_ALIASES.keys())
+
+
+if TYPE_CHECKING:
+    from krons import agent as agent
+    from krons import resource as resource
+    from krons import session as session
+    from krons import work as work
+    from krons.core import specs as specs
+    from krons.core import types as types
+    from krons.work import operations as operations

krons/agent/__init__.py

@@ -0,0 +1,144 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agents module - AI provider integrations, message handling, and operations.
+
+Submodules:
+    providers: API endpoint implementations (OpenAI, Anthropic, Gemini, Claude Code)
+    message: Message content types and preparation
+    mcps: MCP (Model Context Protocol) connection management
+    operations: Agent operation primitives (generate, parse, act, react)
+    third_party: Provider-specific request/response models
+    tool: Callable function backends
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Lazy import mapping
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # tool.py
+    "Tool": ("krons.agent.tool", "Tool"),
+    "ToolCalling": ("krons.agent.tool", "ToolCalling"),
+    "ToolConfig": ("krons.agent.tool", "ToolConfig"),
+    "tool": ("krons.agent.tool", "tool"),
+    # providers
+    "AnthropicMessagesEndpoint": (
+        "krons.agent.providers",
+        "AnthropicMessagesEndpoint",
+    ),
+    "GeminiCodeEndpoint": ("krons.agent.providers", "GeminiCodeEndpoint"),
+    "OAIChatEndpoint": ("krons.agent.providers", "OAIChatEndpoint"),
+    "create_anthropic_config": ("krons.agent.providers", "create_anthropic_config"),
+    "create_gemini_code_config": (
+        "krons.agent.providers",
+        "create_gemini_code_config",
+    ),
+    "create_oai_chat": ("krons.agent.providers", "create_oai_chat"),
+    "match_endpoint": ("krons.agent.providers", "match_endpoint"),
+    # message
+    "ActionRequest": ("krons.agent.message", "ActionRequest"),
+    "ActionResponse": ("krons.agent.message", "ActionResponse"),
+    "Assistant": ("krons.agent.message", "Assistant"),
+    "Instruction": ("krons.agent.message", "Instruction"),
+    "MessageContent": ("krons.agent.message", "MessageContent"),
+    "MessageRole": ("krons.agent.message", "MessageRole"),
+    "System": ("krons.agent.message", "System"),
+    "prepare_messages_for_chat": ("krons.agent.message", "prepare_messages_for_chat"),
+    # mcps
+    "CommandNotAllowedError": ("krons.agent.mcps", "CommandNotAllowedError"),
+    "DEFAULT_ALLOWED_COMMANDS": ("krons.agent.mcps", "DEFAULT_ALLOWED_COMMANDS"),
+    "MCPConnectionPool": ("krons.agent.mcps", "MCPConnectionPool"),
+    "create_mcp_callable": ("krons.agent.mcps", "create_mcp_callable"),
+    "load_mcp_config": ("krons.agent.mcps", "load_mcp_config"),
+    "load_mcp_tools": ("krons.agent.mcps", "load_mcp_tools"),
+}
+
+_LOADED: dict[str, object] = {}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import attributes on first access."""
+    if name in _LOADED:
+        return _LOADED[name]
+
+    if name in _LAZY_IMPORTS:
+        from importlib import import_module
+
+        module_name, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_name)
+        value = getattr(module, attr_name)
+        _LOADED[name] = value
+        return value
+
+    raise AttributeError(f"module 'krons.agent' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all available attributes for autocomplete."""
+    return list(__all__)
+
+
+# TYPE_CHECKING block for static analysis
+if TYPE_CHECKING:
+    from krons.agent.mcps import (
+        DEFAULT_ALLOWED_COMMANDS,
+        CommandNotAllowedError,
+        MCPConnectionPool,
+        create_mcp_callable,
+        load_mcp_config,
+        load_mcp_tools,
+    )
+    from krons.agent.message import (
+        ActionRequest,
+        ActionResponse,
+        Assistant,
+        Instruction,
+        MessageContent,
+        MessageRole,
+        System,
+        prepare_messages_for_chat,
+    )
+    from krons.agent.providers import (
+        AnthropicMessagesEndpoint,
+        GeminiCodeEndpoint,
+        OAIChatEndpoint,
+        create_anthropic_config,
+        create_gemini_code_config,
+        create_oai_chat,
+        match_endpoint,
+    )
+    from krons.agent.tool import Tool, ToolCalling, ToolConfig, tool
+
+__all__ = [
+    # tool
+    "Tool",
+    "ToolCalling",
+    "ToolConfig",
+    "tool",
+    # providers
+    "AnthropicMessagesEndpoint",
+    "GeminiCodeEndpoint",
+    "OAIChatEndpoint",
+    "create_anthropic_config",
+    "create_gemini_code_config",
+    "create_oai_chat",
+    "match_endpoint",
+    # message
+    "ActionRequest",
+    "ActionResponse",
+    "Assistant",
+    "Instruction",
+    "MessageContent",
+    "MessageRole",
+    "System",
+    "prepare_messages_for_chat",
+    # mcps
+    "CommandNotAllowedError",
+    "DEFAULT_ALLOWED_COMMANDS",
+    "MCPConnectionPool",
+    "create_mcp_callable",
+    "load_mcp_config",
+    "load_mcp_tools",
+]

krons/agent/mcps/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from .loader import create_mcp_callable, load_mcp_config, load_mcp_tools
+from .wrapper import DEFAULT_ALLOWED_COMMANDS, CommandNotAllowedError, MCPConnectionPool
+
+__all__ = (
+    "DEFAULT_ALLOWED_COMMANDS",
+    "CommandNotAllowedError",
+    "MCPConnectionPool",
+    "create_mcp_callable",
+    "load_mcp_config",
+    "load_mcp_tools",
+)

krons/agent/mcps/loader.py

@@ -0,0 +1,287 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+__all__ = ("create_mcp_callable", "load_mcp_config", "load_mcp_tools")
+
+logger = logging.getLogger(__name__)
+
+
+async def load_mcp_tools(
+    registry: Any,
+    server_config: dict[str, Any],
+    tool_names: list[str] | None = None,
+    request_options: dict[str, type] | None = None,
+    update: bool = False,
+) -> list[str]:
+    """Load MCP tools into ResourceRegistry.
+
+    Converts MCP tools to standard Tool instances wrapped in iModel
+    and registers them in the provided ResourceRegistry.
+
+    Args:
+        registry: ResourceRegistry instance to register tools into
+        server_config: MCP server configuration (command, args, etc.)
+                      Can be {"server": "name"} to reference loaded config
+                      or full config dict with command/args
+        tool_names: Optional list of specific tool names to register.
+                   If None, will discover and register all available tools.
+        request_options: Optional dict mapping tool names to Pydantic model classes
+                        for request validation. E.g., {"exa_search": ExaSearchRequest}
+        update: If True, allow updating existing tools.
+
+    Returns:
+        List of registered tool names (qualified with server prefix)
+
+    Example:
+        >>> # Auto-discover all tools
+        >>> tools = await load_mcp_tools(session.registry, {"server": "search"})
+        >>>
+        >>> # Register specific tools with validation
+        >>> from pydantic import BaseModel
+        >>> class SearchRequest(BaseModel):
+        ...     query: str
+        ...     limit: int = 10
+        >>> tools = await load_mcp_tools(
+        ...     session.registry,
+        ...     {"command": "python", "args": ["-m", "server"]},
+        ...     tool_names=["search"],
+        ...     request_options={"search": SearchRequest},
+        ... )
+    """
+    from krons.agent.tool import Tool, ToolConfig
+    from krons.resource import iModel
+
+    from .wrapper import MCPConnectionPool
+
+    registered_tools = []
+
+    # Extract server name for qualified naming
+    server_name = None
+    if isinstance(server_config, dict) and "server" in server_config:
+        server_name = server_config["server"]
+
+    if tool_names:
+        # Register specific tools
+        for tool_name in tool_names:
+            # Qualified name to avoid collisions
+            qualified_name = f"{server_name}_{tool_name}" if server_name else tool_name
+
+            # Check for existing registration
+            if registry.has(qualified_name) and not update:
+                raise ValueError(
+                    f"Tool '{qualified_name}' already registered. Use update=True to replace."
+                )
+
+            # Get request_options for this tool if provided
+            tool_request_options = None
+            if request_options and tool_name in request_options:
+                tool_request_options = request_options[tool_name]
+
+            # Create MCP wrapper callable
+            mcp_callable = create_mcp_callable(
+                server_config=server_config,
+                tool_name=tool_name,
+            )
+
+            # Create and register Tool
+            try:
+                tool = Tool(
+                    func_callable=mcp_callable,
+                    config=ToolConfig(
+                        name=qualified_name,
+                        provider=server_name or "mcp",
+                        request_options=tool_request_options,
+                    ),
+                )
+                model = iModel(backend=tool)
+                registry.register(model, update=update)
+                registered_tools.append(qualified_name)
+            except Exception as e:
+                logger.warning(f"Failed to register tool {tool_name}: {e}")
+    else:
+        # Auto-discover tools from the server
+        client = await MCPConnectionPool.get_client(server_config)
+        tools = await client.list_tools()
+
+        # Register each discovered tool
+        for tool in tools:
+            # Qualified name to avoid collisions
+            qualified_name = f"{server_name}_{tool.name}" if server_name else tool.name
+
+            # Get request_options for this tool if provided
+            tool_request_options = None
+            if request_options and tool.name in request_options:
+                tool_request_options = request_options[tool.name]
+
+            # Extract schema from FastMCP tool directly
+            tool_schema = None
+            try:
+                if (
+                    hasattr(tool, "inputSchema")
+                    and tool.inputSchema is not None
+                    and isinstance(tool.inputSchema, dict)
+                ):
+                    # Format as OpenAI function calling schema
+                    tool_schema = {
+                        "type": "function",
+                        "function": {
+                            "name": qualified_name,  # Use qualified name
+                            "description": (
+                                tool.description
+                                if hasattr(tool, "description") and tool.description
+                                else f"MCP tool: {tool.name}"
+                            ),
+                            "parameters": tool.inputSchema,
+                        },
+                    }
+            except Exception as schema_error:
+                # If schema extraction fails, Tool will auto-generate from callable signature
+                logger.warning(
+                    f"Could not extract schema for {tool.name}: {schema_error}"
+                )
+                tool_schema = None
+
+            try:
+                # Create MCP wrapper callable
+                mcp_callable = create_mcp_callable(
+                    server_config=server_config,
+                    tool_name=tool.name,
+                )
+
+                # Register as regular Tool with MCP-discovered schema
+                if registry.has(qualified_name) and not update:
+                    logger.warning(
+                        f"Tool '{qualified_name}' already registered. Skipping."
+                    )
+                    continue
+
+                tool_obj = Tool(
+                    func_callable=mcp_callable,
+                    config=ToolConfig(
+                        name=qualified_name,
+                        provider=server_name or "mcp",
+                        request_options=tool_request_options,
+                    ),
+                    tool_schema=tool_schema,
+                )
+                model = iModel(backend=tool_obj)
+                registry.register(model, update=update)
+                registered_tools.append(qualified_name)
+            except Exception as e:
+                logger.warning(f"Failed to register tool {tool.name}: {e}")
+
+    return registered_tools
+
+
+def create_mcp_callable(
+    server_config: dict[str, Any],
+    tool_name: str,
+) -> Callable:
+    """Create async callable that wraps MCP tool execution.
+
+    Args:
+        server_config: MCP server configuration
+        tool_name: Original MCP tool name
+
+    Returns:
+        Async callable that executes MCP tool via connection pool
+    """
+    from .wrapper import MCPConnectionPool
+
+    async def mcp_wrapper(**kwargs: Any) -> Any:
+        """Execute MCP tool call via connection pool.
+
+        Args:
+            **kwargs: Tool arguments
+
+        Returns:
+            Tool execution result (normalized)
+        """
+        # Get pooled client
+        client = await MCPConnectionPool.get_client(server_config)
+
+        # Call the tool
+        result = await client.call_tool(tool_name, kwargs)
+
+        # Extract content from FastMCP response
+        if hasattr(result, "content"):
+            content = result.content
+            if isinstance(content, list) and len(content) == 1:
+                item = content[0]
+                if hasattr(item, "text"):
+                    return item.text
+                elif isinstance(item, dict) and item.get("type") == "text":
+                    return item.get("text", "")
+            return content
+        elif isinstance(result, list) and len(result) == 1:
+            item = result[0]
+            if isinstance(item, dict) and item.get("type") == "text":
+                return item.get("text", "")
+
+        return result
+
+    # Set function name for introspection
+    mcp_wrapper.__name__ = tool_name
+
+    return mcp_wrapper
+
+
+async def load_mcp_config(
+    registry: Any,  # ResourceRegistry
+    config_path: str,
+    server_names: list[str] | None = None,
+    update: bool = False,
+) -> dict[str, list[str]]:
+    """Load MCP configurations from a .mcp.json file with auto-discovery.
+
+    Args:
+        registry: ResourceRegistry instance to register tools into
+        config_path: Path to .mcp.json configuration file
+        server_names: Optional list of server names to load.
+                     If None, loads all servers.
+        update: If True, allow updating existing tools.
+
+    Returns:
+        Dict mapping server names to lists of registered tool names
+
+    Example:
+        >>> # Load all servers and auto-discover their tools
+        >>> tools = await load_mcp_config(session.registry, ".mcp.json")
+        >>> print(f"Loaded {sum(len(t) for t in tools.values())} tools")
+        >>>
+        >>> # Load specific servers only
+        >>> tools = await load_mcp_config(
+        ...     session.registry, ".mcp.json", server_names=["search", "memory"]
+        ... )
+    """
+    from .wrapper import MCPConnectionPool
+
+    # Load the config file into the connection pool
+    MCPConnectionPool.load_config(config_path)
+
+    # Get server list to process
+    if server_names is None:
+        # Get all server names from loaded config
+        server_names = list(MCPConnectionPool._configs.keys())
+
+    # Register tools from each server
+    all_tools = {}
+    for server_name in server_names:
+        try:
+            # Register using server reference
+            tools = await load_mcp_tools(
+                registry, {"server": server_name}, update=update
+            )
+            all_tools[server_name] = tools
+            logger.info(f"✅ Registered {len(tools)} tools from server '{server_name}'")
+        except Exception as e:
+            logger.error(f"⚠️  Failed to register server '{server_name}': {e}")
+            all_tools[server_name] = []
+
+    return all_tools