mcp-proxy-adapter 1.0.0__py3-none-any.whl

openapi_schema/rpc_schema.py

@@ -0,0 +1,416 @@
+"""
+Модуль для создания RPC части OpenAPI схемы.
+Содержит описание единого RPC эндпоинта для вызова команд.
+"""
+from typing import Dict, Any
+
+def get_rpc_schema() -> Dict[str, Any]:
+    """
+    Возвращает RPC часть OpenAPI схемы.
+    
+    Returns:
+        dict: RPC часть OpenAPI схемы
+    """
+    return {
+        "paths": {
+            "/cmd": {
+                "post": {
+                    "summary": "Универсальный RPC эндпоинт для выполнения команд",
+                    "description": "**Основной интерфейс взаимодействия с системой**. Эндпоинт принимает структурированный JSON-RPC 2.0 запрос с командой и параметрами, выполняет указанную операцию и возвращает результат. Поддерживает работу только с векторами размерности 384.",
+                    "operationId": "executeCommand",
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CommandRequest"
+                                }
+                            }
+                        }
+                    },
+                    "responses": {
+                        "200": {
+                            "description": "Результат выполнения команды (независимо от успеха или ошибки). API всегда возвращает код 200 и использует поле 'success' для индикации успеха операции.",
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "$ref": "#/components/schemas/ApiResponse"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "components": {
+            "schemas": {
+                "CommandRequest": {
+                    "properties": {
+                        "command": {
+                            "type": "string",
+                            "title": "Command",
+                            "description": "Название команды для выполнения",
+                            "enum": [
+                                "health", "status", "help", "get_metadata", "get_text",
+                                "create_record", "add_vector", "create_text_record", "add_text",
+                                "search_records", "search_by_vector", "search_text_records",
+                                "search_by_text", "filter_records", "filter", "delete_records",
+                                "delete", "get_by_session_message"
+                            ]
+                        },
+                        "params": {
+                            "title": "Params",
+                            "description": "Параметры команды",
+                            "type": "object",
+                            "additionalProperties": True
+                        },
+                        "jsonrpc": {
+                            "type": "string",
+                            "description": "Версия JSON-RPC протокола",
+                            "enum": ["2.0"],
+                            "default": "2.0"
+                        },
+                        "id": {
+                            "type": "string",
+                            "description": "Идентификатор запроса (опционально)"
+                        }
+                    },
+                    "type": "object",
+                    "required": ["command"],
+                    "title": "CommandRequest",
+                    "description": "Модель для запроса выполнения команды векторного хранилища"
+                },
+                "JsonRpcResponse": {
+                    "type": "object",
+                    "required": ["jsonrpc", "success"],
+                    "properties": {
+                        "jsonrpc": {
+                            "type": "string",
+                            "description": "Версия JSON-RPC протокола",
+                            "enum": ["2.0"],
+                            "default": "2.0"
+                        },
+                        "success": {
+                            "type": "boolean",
+                            "description": "Индикатор успешности операции",
+                            "default": False
+                        },
+                        "result": {
+                            "description": "Результат операции. Присутствует только при успешном выполнении (success=True). Формат результата зависит от выполненной команды."
+                        },
+                        "error": {
+                            "description": "Информация об ошибке. Присутствует только при возникновении ошибки (success=\"false\").",
+                            "type": "object",
+                            "required": ["code", "message"],
+                            "properties": {
+                                "code": {
+                                    "type": "integer",
+                                    "description": "Код ошибки (внутренний код, не HTTP-статус)",
+                                    "example": 400
+                                },
+                                "message": {
+                                    "type": "string",
+                                    "description": "Текстовое описание ошибки",
+                                    "example": "Запись не существует: ID 12345"
+                                }
+                            }
+                        },
+                        "id": {
+                            "type": "string",
+                            "description": "Идентификатор запроса (если был указан в запросе)"
+                        }
+                    },
+                    "example": {
+                        "jsonrpc": "2.0",
+                        "success": True,
+                        "result": {"id": "550e8400-e29b-41d4-a716-446655440000"}
+                    }
+                },
+                "HealthParams": {
+                    "type": "object",
+                    "properties": {},
+                    "title": "HealthParams",
+                    "description": "Параметры для команды health"
+                },
+                "StatusParams": {
+                    "type": "object",
+                    "properties": {},
+                    "title": "StatusParams",
+                    "description": "Параметры для команды status"
+                },
+                "HelpParams": {
+                    "type": "object",
+                    "properties": {},
+                    "title": "HelpParams",
+                    "description": "Параметры для команды help"
+                },
+                "GetMetadataParams": {
+                    "type": "object",
+                    "properties": {
+                        "id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор записи"
+                        }
+                    },
+                    "required": ["id"],
+                    "title": "GetMetadataParams",
+                    "description": "Параметры для команды get_metadata"
+                },
+                "GetTextParams": {
+                    "type": "object",
+                    "properties": {
+                        "id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор записи"
+                        }
+                    },
+                    "required": ["id"],
+                    "title": "GetTextParams",
+                    "description": "Параметры для команды get_text"
+                },
+                "CreateRecordParams": {
+                    "type": "object",
+                    "properties": {
+                        "vector": {
+                            "$ref": "#/components/schemas/Vector"
+                        },
+                        "metadata": {
+                            "type": "object",
+                            "description": "Метаданные записи"
+                        },
+                        "session_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сессии (опционально)"
+                        },
+                        "message_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сообщения (опционально)"
+                        },
+                        "timestamp": {
+                            "type": "string",
+                            "format": "date-time",
+                            "description": "Временная метка в формате ISO 8601 (опционально)"
+                        }
+                    },
+                    "required": ["vector"],
+                    "title": "CreateRecordParams",
+                    "description": "Параметры для создания новой векторной записи"
+                },
+                "CreateTextRecordParams": {
+                    "type": "object",
+                    "properties": {
+                        "text": {
+                            "type": "string",
+                            "description": "Текст для векторизации"
+                        },
+                        "metadata": {
+                            "type": "object",
+                            "description": "Метаданные записи"
+                        },
+                        "model": {
+                            "type": "string",
+                            "description": "Модель для векторизации (опционально)"
+                        },
+                        "session_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сессии (опционально)"
+                        },
+                        "message_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сообщения (опционально)"
+                        },
+                        "timestamp": {
+                            "type": "string",
+                            "format": "date-time",
+                            "description": "Временная метка в формате ISO 8601 (опционально)"
+                        }
+                    },
+                    "required": ["text"],
+                    "title": "CreateTextRecordParams",
+                    "description": "Параметры для создания новой текстовой записи"
+                },
+                "SearchRecordsParams": {
+                    "type": "object",
+                    "properties": {
+                        "vector": {
+                            "$ref": "#/components/schemas/Vector"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Максимальное количество результатов",
+                            "default": 10
+                        },
+                        "threshold": {
+                            "type": "number",
+                            "description": "Порог схожести (от 0 до 1)",
+                            "default": 0.7
+                        }
+                    },
+                    "required": ["vector"],
+                    "title": "SearchRecordsParams",
+                    "description": "Параметры для поиска векторных записей"
+                },
+                "SearchTextRecordsParams": {
+                    "type": "object",
+                    "properties": {
+                        "text": {
+                            "type": "string",
+                            "description": "Текст для поиска"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Максимальное количество результатов",
+                            "default": 10
+                        },
+                        "threshold": {
+                            "type": "number",
+                            "description": "Порог схожести (от 0 до 1)",
+                            "default": 0.7
+                        }
+                    },
+                    "required": ["text"],
+                    "title": "SearchTextRecordsParams",
+                    "description": "Параметры для поиска текстовых записей"
+                },
+                "FilterRecordsParams": {
+                    "type": "object",
+                    "properties": {
+                        "metadata": {
+                            "type": "object",
+                            "description": "Критерии фильтрации по метаданным"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Максимальное количество результатов",
+                            "default": 10
+                        }
+                    },
+                    "required": ["metadata"],
+                    "title": "FilterRecordsParams",
+                    "description": "Параметры для фильтрации записей"
+                },
+                "DeleteRecordsParams": {
+                    "type": "object",
+                    "properties": {
+                        "ids": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "format": "uuid"
+                            },
+                            "description": "Список UUID4 идентификаторов записей для удаления"
+                        }
+                    },
+                    "required": ["ids"],
+                    "title": "DeleteRecordsParams",
+                    "description": "Параметры для удаления записей"
+                },
+                "GetBySessionMessageParams": {
+                    "type": "object",
+                    "properties": {
+                        "session_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сессии"
+                        },
+                        "message_id": {
+                            "type": "string",
+                            "format": "uuid",
+                            "description": "UUID4 идентификатор сообщения"
+                        }
+                    },
+                    "required": ["session_id", "message_id"],
+                    "title": "GetBySessionMessageParams",
+                    "description": "Параметры для получения записи по идентификаторам сессии и сообщения"
+                }
+            },
+            "examples": {
+                "health_check": {
+                    "summary": "Проверка доступности сервиса",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "health",
+                        "id": "1"
+                    }
+                },
+                "create_vector": {
+                    "summary": "Создание векторной записи",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "create_record",
+                        "params": {
+                            "vector": [0.1] * 384,
+                            "metadata": {"source": "test"}
+                        },
+                        "id": "2"
+                    }
+                },
+                "search_by_vector": {
+                    "summary": "Поиск по вектору",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "search_records",
+                        "params": {
+                            "vector": [0.1] * 384,
+                            "limit": 5
+                        },
+                        "id": "3"
+                    }
+                },
+                "search_by_text": {
+                    "summary": "Поиск по тексту",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "search_text_records",
+                        "params": {
+                            "text": "пример поиска",
+                            "limit": 5
+                        },
+                        "id": "4"
+                    }
+                },
+                "filter_records": {
+                    "summary": "Фильтрация записей",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "filter_records",
+                        "params": {
+                            "metadata": {"source": "test"},
+                            "limit": 10
+                        },
+                        "id": "5"
+                    }
+                },
+                "delete_records": {
+                    "summary": "Удаление записей",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "delete_records",
+                        "params": {
+                            "ids": ["550e8400-e29b-41d4-a716-446655440000"]
+                        },
+                        "id": "6"
+                    }
+                },
+                "get_by_session_message": {
+                    "summary": "Получение записи по идентификаторам",
+                    "value": {
+                        "jsonrpc": "2.0",
+                        "command": "get_by_session_message",
+                        "params": {
+                            "session_id": "550e8400-e29b-41d4-a716-446655440000",
+                            "message_id": "660e8400-e29b-41d4-a716-446655440000"
+                        },
+                        "id": "7"
+                    }
+                }
+            }
+        }
+    } 

validators/__init__.py

@@ -0,0 +1,14 @@
+"""
+Validators for checking the correspondence between metadata and function signatures.
+
+This module contains classes for validating the correspondence between command metadata
+and signatures and docstrings of handler functions.
+"""
+
+from .docstring_validator import DocstringValidator
+from .metadata_validator import MetadataValidator
+
+__all__ = [
+    'DocstringValidator',
+    'MetadataValidator',
+] 

validators/base_validator.py

@@ -0,0 +1,23 @@
+"""
+Base class for command validators.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Tuple
+
+class BaseValidator(ABC):
+    """
+    Base class for all command validators.
+    
+    Defines a common interface for validating command handler functions,
+    their docstrings, metadata, and other aspects.
+    """
+    
+    @abstractmethod
+    def validate(self, *args, **kwargs) -> Tuple[bool, List[str]]:
+        """
+        Main validation method.
+        
+        Returns:
+            Tuple[bool, List[str]]: Validity flag and list of errors
+        """
+        pass 

validators/docstring_validator.py

@@ -0,0 +1,75 @@
+"""
+Validator for checking the correspondence between docstrings and function signatures.
+"""
+import inspect
+from typing import Dict, Any, Optional, Callable, List, Tuple, get_type_hints
+import docstring_parser
+
+class DocstringValidator:
+    """
+    Validator for checking the correspondence between docstrings and handler functions.
+    
+    This class verifies that function docstrings match their signatures,
+    contain all necessary sections, and describe all parameters.
+    """
+    
+    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """
+        Validates the function's docstring against its formal parameters.
+        
+        Args:
+            handler: Command handler function
+            command_name: Command name
+            metadata: Command metadata
+            
+        Returns:
+            Tuple[bool, List[str]]: Validity flag and list of errors
+        """
+        errors = []
+        
+        # Get formal parameters of the function
+        sig = inspect.signature(handler)
+        formal_params = list(sig.parameters.keys())
+        
+        # Skip self parameter for methods
+        if formal_params and formal_params[0] == 'self':
+            formal_params = formal_params[1:]
+            
+        # Parse docstring
+        docstring = handler.__doc__ or ""
+        parsed_doc = docstring_parser.parse(docstring)
+        
+        # Check for function description
+        if not parsed_doc.short_description and not parsed_doc.long_description:
+            errors.append(f"Missing function description")
+        
+        # Get parameters from docstring
+        doc_params = {param.arg_name: param for param in parsed_doc.params}
+        
+        # Check that all formal parameters are described in the docstring
+        for param in formal_params:
+            # Skip special parameters
+            if param in ('params', 'kwargs'):
+                continue
+                
+            if param not in doc_params:
+                errors.append(f"Parameter '{param}' is not described in the function docstring")
+        
+        # Check for returns in docstring
+        if not parsed_doc.returns and not any(t.type_name == 'Returns' for t in parsed_doc.meta):
+            errors.append(f"Missing return value description in the function docstring")
+        
+        # Check for type annotations
+        try:
+            type_hints = get_type_hints(handler)
+            for param in formal_params:
+                # Skip special parameters
+                if param in ('params', 'kwargs'):
+                    continue
+                    
+                if param not in type_hints:
+                    errors.append(f"Missing type annotation for parameter '{param}' in function {command_name}")
+        except Exception as e:
+            errors.append(f"Error getting type hints: {str(e)}")
+        
+        return len(errors) == 0, errors 

validators/metadata_validator.py

@@ -0,0 +1,76 @@
+"""
+Validator for checking command metadata against function signatures.
+"""
+import inspect
+from typing import Dict, Any, Optional, Callable, List, Tuple
+
+class MetadataValidator:
+    """
+    Validator for checking handler function metadata.
+    
+    This class verifies that command metadata matches function signatures,
+    and all parameters are correctly described.
+    """
+    
+    def validate(self, handler: Callable, command_name: str, metadata: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """
+        Checks if metadata matches function's formal parameters.
+        
+        Args:
+            handler: Command handler function
+            command_name: Command name
+            metadata: Command metadata
+            
+        Returns:
+            Tuple[bool, List[str]]: Validity flag and list of errors
+        """
+        errors = []
+        
+        # Check presence of main fields in metadata
+        if not metadata.get('description'):
+            errors.append(f"Missing description for command '{command_name}'")
+            
+        # Get function's formal parameters
+        sig = inspect.signature(handler)
+        formal_params = list(sig.parameters.keys())
+        
+        # Skip self parameter for methods
+        if formal_params and formal_params[0] == 'self':
+            formal_params = formal_params[1:]
+            
+        # Check presence of parameters in metadata
+        if 'parameters' not in metadata or not isinstance(metadata['parameters'], dict):
+            errors.append(f"Parameters are missing or incorrectly defined in metadata for command '{command_name}'")
+            return False, errors
+            
+        meta_params = metadata['parameters']
+        
+        # Check that all formal parameters are in metadata
+        for param in formal_params:
+            # Skip special parameters
+            if param in ('params', 'kwargs'):
+                continue
+                
+            if param not in meta_params:
+                errors.append(f"Parameter '{param}' is not described in metadata for command '{command_name}'")
+                continue
+                
+            param_info = meta_params[param]
+            
+            # Check presence of required fields for parameter
+            if not isinstance(param_info, dict):
+                errors.append(f"Incorrect format for parameter '{param}' description in metadata for command '{command_name}'")
+                continue
+                
+            if 'type' not in param_info:
+                errors.append(f"Type is not specified for parameter '{param}' in metadata for command '{command_name}'")
+                
+            if 'description' not in param_info:
+                errors.append(f"Description is not specified for parameter '{param}' in metadata for command '{command_name}'")
+        
+        # Check that there are no extra parameters in metadata
+        for param in meta_params:
+            if param not in formal_params and param not in ('params', 'kwargs'):
+                errors.append(f"Extra parameter '{param}' in metadata for command '{command_name}'")
+        
+        return len(errors) == 0, errors