matimo-core 0.1.0__py3-none-any.whl

matimo/__init__.py

@@ -0,0 +1,318 @@
+"""
+Matimo Python SDK — Public API
+================================
+
+Write tools once in YAML, use them everywhere.
+
+Quick start:
+    from matimo import Matimo
+
+    matimo = await Matimo.init('./tools')
+    result = await matimo.execute('my_tool', {'param': 'value'})
+
+LangChain integration:
+    from matimo import Matimo, convert_tools_to_langchain
+    matimo = await Matimo.init('./tools')
+    tools = convert_tools_to_langchain(matimo.list_tools(), matimo)
+
+CrewAI integration:
+    from matimo import Matimo, convert_tools_to_crewai
+    matimo = await Matimo.init('./tools')
+    tools = convert_tools_to_crewai(matimo.list_tools(), matimo)
+"""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from matimo.instance import Matimo
+
+# Approval
+from matimo.approval.handler import (
+    ApprovalCallback,
+    ApprovalHandler,
+    ApprovalRequest,
+    get_global_approval_handler,
+    set_global_approval_handler,
+)
+
+# Auth
+from matimo.auth.injection import extract_parameter_placeholders, inject_auth_parameters
+from matimo.auth.oauth2_config import (
+    AuthorizationOptions,
+    OAuth2Config,
+    OAuth2Token,
+    TokenResponse,
+)
+from matimo.auth.oauth2_handler import OAuth2Handler
+from matimo.auth.oauth2_provider_loader import OAuth2ProviderLoader
+
+# Core loading + registry
+from matimo.core.loader import ToolLoader
+
+# Core models
+from matimo.core.models import (
+    AuthConfig,
+    AuthType,
+    BundledResources,
+    CommandExecution,
+    ExecuteOptions,
+    ExecutionResult,
+    FunctionExecution,
+    HttpExecution,
+    OutputSchema,
+    Parameter,
+    ParameterEncoding,
+    ParameterEncodingConfig,
+    ParameterEncodingType,
+    ParameterType,
+    ParsedSkill,
+    PolicyContext,
+    ProviderDefinition,
+    RateLimitConfig,
+    SearchSkillsOptions,
+    SkillContentOptions,
+    SkillDefinition,
+    SkillFrontmatter,
+    SkillSection,
+    SkillSummary,
+    ToolDefinition,
+    ToolExample,
+    ToolStatus,
+    ValidationError,
+    ValidationResult,
+)
+from matimo.core.registry import ToolRegistry
+
+# Skills
+from matimo.core.skill_content_parser import (
+    ParsedSkillContent,
+    extract_skill_content,
+    list_skill_sections,
+    parse_skill_sections,
+)
+from matimo.core.skill_loader import SkillLoader, extract_skill_metadata, parse_skill_content
+from matimo.core.skill_registry import SemanticSearchResult, SkillRegistry
+from matimo.core.tfidf_embedding import (
+    EmbeddingProvider,
+    TfIdfEmbeddingProvider,
+    cosine_similarity,
+)
+
+# Decorators
+from matimo.decorators import (
+    get_global_matimo_instance,
+    set_global_matimo_instance,
+    tool,
+)
+
+# Encodings
+from matimo.encodings.parameter_encoding import apply_parameter_encodings
+
+# Errors
+from matimo.errors import (
+    ErrorCode,
+    MatimoError,
+    create_execution_error,
+    create_validation_error,
+    from_http_error,
+)
+
+# Executors
+from matimo.executors.command_executor import CommandExecutor
+from matimo.executors.function_executor import FunctionExecutor
+from matimo.executors.http_executor import HttpExecutor
+
+# Main entry point + sync API
+from matimo.instance import InitOptions, Matimo, ReloadResult, matimo
+
+# Logging
+from matimo.logging import (
+    MatimoLogger,
+    get_global_matimo_logger,
+    set_global_matimo_logger,
+    setup_logger,
+)
+
+# MCP
+from matimo.mcp.secrets import (
+    AwsSecretsManagerResolver,
+    DotenvSecretResolver,
+    EnvSecretResolver,
+    SecretResolverChain,
+    VaultSecretResolver,
+    create_resolver_chain,
+)
+from matimo.mcp.server import MCPServer, MCPServerOptions, create_mcp_server
+from matimo.mcp.tool_converter import convert_parameters_to_mcp_schema
+
+# Policy
+from matimo.policy.approval_manifest import ApprovalManifest, ApprovalRecord
+from matimo.policy.content_validator import ContentViolation, validate_tool_content
+from matimo.policy.default_policy import DefaultPolicyEngine, PolicyEngine, get_tier_for_tool
+from matimo.policy.integrity_tracker import IntegrityAction, ToolIntegrityTracker
+from matimo.policy.policy_loader import load_policy_from_file
+from matimo.policy.risk_classifier import classify_risk
+from matimo.policy.types import (
+    HITLCallback,
+    HITLRequest,
+    MatimoEvent,
+    MatimoEventHandler,
+    PolicyAllowed,
+    PolicyConfig,
+    PolicyDecision,
+    PolicyDenied,
+    PolicyPendingApproval,
+    PolicyTier,
+    RiskLevel,
+)
+from matimo.sync import MatimoSync
+
+__version__ = "0.1.0"
+
+
+def get_core_tools_path() -> str:
+    """Return the absolute path to the bundled core tool definitions.
+
+    Used as a ``matimo.providers`` entry point so that core meta-tools
+    (execute, read, edit, search, web, calculator, matimo_create_tool, …)
+    are auto-discovered by :meth:`matimo.Matimo.init` when
+    ``auto_discover=True``.
+    """
+    try:
+        ref = importlib.resources.files("matimo") / "tools"
+        return str(ref)
+    except Exception:
+        return str(Path(__file__).parent / "tools")
+
+# ---------------------------------------------------------------------------
+# Integrations (lazy — raise ImportError with hint on missing optional dep)
+# ---------------------------------------------------------------------------
+
+
+def convert_tools_to_langchain(
+    tools: list[Any],
+    matimo_instance: Matimo,
+    credentials: dict[str, str] | None = None,
+) -> list[Any]:
+    """Convert Matimo tools to LangChain StructuredTool list. Requires langchain-core."""
+    from matimo.integrations.langchain import convert_tools_to_langchain as _inner
+    return _inner(tools, matimo_instance, credentials)
+
+
+def get_skills_metadata(matimo_instance: Matimo) -> list[dict[str, str]]:
+    """Return Level-1 metadata (name + description) for all available skills."""
+    from matimo.integrations.langchain import get_skills_metadata as _inner
+    return _inner(matimo_instance)
+
+
+async def build_relevant_skill_prompt(
+    matimo_instance: Matimo,
+    query: str,
+    *,
+    top_k: int = 3,
+    min_score: float = 0.3,
+    header: str | None = None,
+) -> str:
+    """Build a per-request skill context prompt using TF-IDF semantic search."""
+    from matimo.integrations.langchain import build_relevant_skill_prompt as _inner
+    return await _inner(matimo_instance, query, top_k=top_k, min_score=min_score, header=header)
+
+
+def convert_tools_to_crewai(
+    tools: list[Any],
+    matimo_instance: Matimo,
+    credentials: dict[str, str] | None = None,
+) -> list[Any]:
+    """Convert Matimo tools to CrewAI BaseTool list. Requires crewai."""
+    from matimo.integrations.crewai import convert_tools_to_crewai as _inner
+    return _inner(tools, matimo_instance, credentials)
+
+
+# ---------------------------------------------------------------------------
+# Decorators
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Synchronous API
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    # Core models
+    "ToolDefinition", "Parameter", "ParameterType", "AuthConfig", "AuthType",
+    "HttpExecution", "CommandExecution", "FunctionExecution",
+    "OutputSchema", "RateLimitConfig", "ToolExample",
+    "ParameterEncoding", "ParameterEncodingConfig", "ParameterEncodingType",
+    "ToolStatus",
+    "ExecutionResult", "ExecuteOptions", "PolicyContext",
+    "ValidationError", "ValidationResult",
+    "ParsedSkill", "SkillFrontmatter", "ProviderDefinition",
+    "SkillDefinition", "SkillSummary", "SkillSection", "SkillContentOptions",
+    "SearchSkillsOptions", "BundledResources",
+    # Core
+    "ToolLoader", "ToolRegistry",
+    # Skills
+    "SkillLoader", "SkillRegistry",
+    "parse_skill_content", "extract_skill_metadata",
+    "parse_skill_sections", "extract_skill_content", "list_skill_sections",
+    "ParsedSkillContent", "SemanticSearchResult",
+    "TfIdfEmbeddingProvider", "EmbeddingProvider", "cosine_similarity",
+    # Executors
+    "HttpExecutor", "CommandExecutor", "FunctionExecutor",
+    # Auth
+    "inject_auth_parameters", "extract_parameter_placeholders",
+    "OAuth2Handler", "OAuth2ProviderLoader",
+    "OAuth2Config", "OAuth2Token", "AuthorizationOptions", "TokenResponse",
+    # Approval
+    "ApprovalHandler", "ApprovalRequest", "ApprovalCallback",
+    "get_global_approval_handler", "set_global_approval_handler",
+    # Encodings
+    "apply_parameter_encodings",
+    # Policy
+    "PolicyEngine", "DefaultPolicyEngine", "PolicyConfig",
+    "PolicyDecision", "PolicyAllowed", "PolicyDenied", "PolicyPendingApproval",
+    "RiskLevel", "PolicyTier",
+    "MatimoEvent", "MatimoEventHandler", "HITLCallback", "HITLRequest",
+    "ContentViolation", "validate_tool_content",
+    "classify_risk", "get_tier_for_tool",
+    "ToolIntegrityTracker", "IntegrityAction",
+    "ApprovalManifest", "ApprovalRecord",
+    "load_policy_from_file",
+    # MCP
+    "MCPServer", "MCPServerOptions", "create_mcp_server",
+    "convert_parameters_to_mcp_schema",
+    "EnvSecretResolver", "DotenvSecretResolver",
+    "VaultSecretResolver", "AwsSecretsManagerResolver",
+    "SecretResolverChain", "create_resolver_chain",
+    # Integrations
+    "convert_tools_to_langchain",
+    "get_skills_metadata",
+    "build_relevant_skill_prompt",
+    "convert_tools_to_crewai",
+    # Decorators
+    "tool", "set_global_matimo_instance", "get_global_matimo_instance",
+    # Logging
+    "MatimoLogger", "setup_logger",
+    "get_global_matimo_logger", "set_global_matimo_logger",
+    # Errors
+    "MatimoError", "ErrorCode",
+    "create_execution_error", "create_validation_error", "from_http_error",
+    # Instance
+    "Matimo", "MatimoSync", "matimo", "InitOptions", "ReloadResult",
+    # Core tools path (entry point)
+    "get_core_tools_path",
+]

matimo/approval/handler.py

@@ -0,0 +1,152 @@
+"""
+Approval handler — human-in-the-loop approval gating for sensitive tools.
+Mirrors: packages/core/src/approval/approval-handler.ts
+"""
+from __future__ import annotations
+
+import fnmatch
+import logging
+import os
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger("matimo")
+
+# Destructive action keywords that trigger approval prompts
+DEFAULT_DESTRUCTIVE_KEYWORDS: list[str] = [
+    "CREATE", "DELETE", "DESTROY", "DROP", "ALTER", "TRUNCATE", "UPDATE",
+    "INSERT", "UPSERT", "REPLACE", "MERGE", "GRANT", "REVOKE",
+    "EDIT", "WRITE", "APPEND", "REMOVE", "PURGE", "RENAME", "SHUTDOWN",
+    "EXECUTE", "EXEC",
+]
+
+
+@dataclass
+class ApprovalRequest:
+    """Represents a pending approval for a tool execution."""
+
+    tool_name: str
+    description: str | None
+    params: dict[str, Any]
+
+
+ApprovalCallback = Callable[[ApprovalRequest], Awaitable[bool]]
+
+
+class ApprovalHandler:
+    """
+    Manages interactive approval gating for sensitive tool executions.
+    Mirrors: ApprovalHandler in approval-handler.ts
+
+    Approval flow:
+    1. auto_approve=True (MATIMO_AUTO_APPROVE env) → always approve
+    2. tool_name matches an approved pattern → approve
+    3. HITL callback set → invoke it and return its decision
+    4. Default → deny
+    """
+
+    def __init__(self) -> None:
+        self.auto_approve: bool = (
+            os.environ.get("MATIMO_AUTO_APPROVE", "").lower() == "true"
+        )
+        self.approved_patterns: set[str] = self._load_approved_patterns()
+        self.destructive_keywords: list[str] = list(DEFAULT_DESTRUCTIVE_KEYWORDS)
+        self._callback: ApprovalCallback | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def set_approval_callback(self, callback: ApprovalCallback) -> None:
+        """Wire an async approval callback (e.g., Slack DM, CLI prompt)."""
+        self._callback = callback
+
+    async def request_approval(self, request: ApprovalRequest) -> bool:
+        """
+        Gate execution on approval.
+        Returns True if approved, False if denied.
+        """
+        # 1. Hard auto-approve (CI / testing)
+        if self.auto_approve:
+            logger.debug(
+                "Auto-approving tool '%s' (MATIMO_AUTO_APPROVE=true)", request.tool_name
+            )
+            return True
+
+        # 2. Pattern allowlist
+        if self._matches_approved_pattern(request.tool_name):
+            logger.debug(
+                "Tool '%s' matches approved pattern — skipping approval prompt",
+                request.tool_name,
+            )
+            return True
+
+        # 3. HITL callback
+        if self._callback is not None:
+            approved = await self._callback(request)
+            if not approved:
+                logger.info(
+                    "Approval denied for tool '%s' by callback", request.tool_name
+                )
+            return approved
+
+        # 4. No callback → default deny
+        logger.warning(
+            "Approval required for tool '%s' but no callback configured — denying",
+            request.tool_name,
+        )
+        return False
+
+    def is_destructive(self, tool_name: str, params: dict[str, Any]) -> bool:
+        """
+        Heuristically determine whether a tool invocation is destructive,
+        based on keyword scanning of the tool name and string parameter values.
+        """
+        combined = tool_name.upper()
+        for v in params.values():
+            if isinstance(v, str):
+                combined += " " + v.upper()
+
+        return any(kw in combined for kw in self.destructive_keywords)
+
+    def add_approved_pattern(self, pattern: str) -> None:
+        """Add a glob pattern to the pre-approved tool allowlist."""
+        self.approved_patterns.add(pattern)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _load_approved_patterns(self) -> set[str]:
+        raw = os.environ.get("MATIMO_APPROVED_PATTERNS", "")
+        if not raw:
+            return set()
+        return {p.strip() for p in raw.split(",") if p.strip()}
+
+    def _matches_approved_pattern(self, tool_name: str) -> bool:
+        return any(
+            fnmatch.fnmatch(tool_name, pattern)
+            for pattern in self.approved_patterns
+        )
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_global_handler: ApprovalHandler | None = None
+
+
+def get_global_approval_handler() -> ApprovalHandler:
+    """Return the global ApprovalHandler, creating one if necessary."""
+    global _global_handler
+    if _global_handler is None:
+        _global_handler = ApprovalHandler()
+    return _global_handler
+
+
+def set_global_approval_handler(handler: ApprovalHandler) -> None:
+    """Replace the global approval handler (useful in tests)."""
+    global _global_handler
+    _global_handler = handler

matimo/auth/__init__.py

@@ -0,0 +1,27 @@
+"""
+Matimo auth module — injection helpers and OAuth2 support.
+
+Mirrors: packages/core/src/auth/
+"""
+from matimo.auth.injection import extract_parameter_placeholders, inject_auth_parameters
+from matimo.auth.oauth2_config import (
+    AuthorizationOptions,
+    OAuth2Config,
+    OAuth2Token,
+    TokenResponse,
+)
+from matimo.auth.oauth2_handler import OAuth2Handler
+from matimo.auth.oauth2_provider_loader import OAuth2ProviderLoader
+
+__all__ = [
+    # Injection
+    "inject_auth_parameters",
+    "extract_parameter_placeholders",
+    # OAuth2
+    "AuthorizationOptions",
+    "OAuth2Config",
+    "OAuth2Handler",
+    "OAuth2ProviderLoader",
+    "OAuth2Token",
+    "TokenResponse",
+]

matimo/auth/injection.py

@@ -0,0 +1,141 @@
+"""
+Auth parameter injection.
+Mirrors: MatimoInstance.injectAuthParameters() in matimo-instance.ts
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Any
+
+from matimo.core.models import ToolDefinition
+
+logger = logging.getLogger("matimo")
+
+# Patterns that indicate a parameter placeholder is auth-related
+_AUTH_PATTERNS = (
+    "token", "key", "secret", "password", "credential",
+    "auth", "bearer", "api_key",
+)
+
+_PLACEHOLDER_RE = re.compile(r"\{([^}]+)\}")
+
+
+def inject_auth_parameters(
+    tool: ToolDefinition,
+    params: dict[str, Any],
+    credentials: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """
+    Scan all placeholders in the tool's execution config (URL, headers, body,
+    query_params). For any placeholder that looks auth-related and has no value
+    in params, attempt to resolve it from:
+      1. per-call credentials dict
+      2. process environment (MATIMO_{TOOL_NAME}_{KEY} or just {KEY})
+
+    SECURITY: injected values are never logged.
+
+    Returns a new params dict with the resolved auth values merged in.
+    """
+    placeholders = extract_parameter_placeholders(tool)
+    result = dict(params)
+
+    for placeholder in placeholders:
+        # Already supplied by the caller
+        if placeholder in result:
+            continue
+
+        lower = placeholder.lower()
+        is_auth = any(pattern in lower for pattern in _AUTH_PATTERNS)
+        if not is_auth:
+            continue
+
+        # Attempt resolution
+        value = _resolve_auth_value(tool.name, placeholder, credentials)
+        if value is not None:
+            result[placeholder] = value
+            logger.debug(
+                "Injected auth parameter '%s' for tool '%s'",
+                placeholder, tool.name
+            )
+
+    return result
+
+
+def extract_parameter_placeholders(tool: ToolDefinition) -> set[str]:
+    """
+    Extract all {placeholder} names from the tool's execution config
+    (url, headers, body, query_params, params, args).
+    Mirrors: extractParameterPlaceholders() in matimo-instance.ts
+    """
+    placeholders: set[str] = set()
+    exec_cfg = tool.execution
+    exec_type = exec_cfg.type
+
+    if exec_type == "http":
+        _scan_string(exec_cfg.url, placeholders)  # type: ignore[attr-defined]
+        _scan_object(exec_cfg.headers, placeholders)  # type: ignore[attr-defined]
+        _scan_object(exec_cfg.body, placeholders)  # type: ignore[attr-defined]
+        _scan_object(exec_cfg.query_params, placeholders)  # type: ignore[attr-defined]
+        _scan_object(exec_cfg.params, placeholders)  # type: ignore[attr-defined]
+
+    elif exec_type == "command":
+        _scan_string(exec_cfg.command, placeholders)  # type: ignore[attr-defined]
+        for arg in exec_cfg.args or []:  # type: ignore[attr-defined]
+            _scan_string(arg, placeholders)
+
+    elif exec_type == "function":
+        # Function tools may have params passed directly — nothing to scan
+        pass
+
+    return placeholders
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_auth_value(
+    tool_name: str,
+    placeholder: str,
+    credentials: dict[str, str] | None,
+) -> str | None:
+    """
+    Try to resolve an auth placeholder in priority order:
+    1. per-call credentials
+    2. env MATIMO_{TOOL_NAME_UPPER}_{PLACEHOLDER_UPPER}
+    3. env {PLACEHOLDER} directly
+    """
+    if credentials and placeholder in credentials:
+        return credentials[placeholder]
+
+    # e.g. MATIMO_SLACK_SLACK_BOT_TOKEN
+    env_key_prefixed = f"MATIMO_{tool_name.upper()}_{placeholder.upper()}"
+    val = os.environ.get(env_key_prefixed)
+    if val:
+        return val
+
+    # env directly (e.g. SLACK_BOT_TOKEN)
+    return os.environ.get(placeholder)
+
+
+def _scan_string(value: str | None, out: set[str]) -> None:
+    if value is None:
+        return
+    for m in _PLACEHOLDER_RE.finditer(value):
+        out.add(m.group(1))
+
+
+def _scan_object(obj: object, out: set[str]) -> None:
+    if obj is None:
+        return
+    if isinstance(obj, str):
+        _scan_string(obj, out)
+    elif isinstance(obj, dict):
+        for v in obj.values():
+            _scan_object(v, out)
+    elif isinstance(obj, list):
+        for item in obj:
+            _scan_object(item, out)