isa-common 0.1.0__tar.gz

isa_common-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: isa-common
+Version: 0.1.0
+Summary: Shared Python infrastructure library for isA platform
+Home-page: https://github.com/isa-platform/isA_Cloud
+Author: isA Platform
+Author-email: isA Platform <dev@isa-platform.com>
+Project-URL: Homepage, https://github.com/isa-platform/isA_Cloud
+Project-URL: Repository, https://github.com/isa-platform/isA_Cloud
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.50.0
+Requires-Dist: grpcio-tools>=1.50.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# isA Common
+
+Shared Python infrastructure library for the isA platform.
+
+## Overview
+
+This package provides common infrastructure components used across all isA Python services:
+- **gRPC Clients**: NATS, MinIO, MQTT, DuckDB, Supabase, etc.
+- **Event Framework**: Generic event-driven architecture base classes
+- **Proto Files**: Generated gRPC proto files
+
+## Installation
+
+### Development Install (Recommended)
+
+```bash
+pip install -e /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+```
+
+### From Source
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+pip install .
+```
+
+## Usage
+
+### gRPC Clients
+
+```python
+from grpc_clients import NATSClient, MinIOClient, get_client
+
+# Option 1: Direct instantiation
+nats = NATSClient(host='localhost', port=50056)
+
+# Option 2: Factory pattern
+nats = get_client('nats', user_id='my_service')
+```
+
+### Event Framework
+
+```python
+from grpc_clients.events import BaseEvent, BaseEventPublisher
+
+# Define your event
+class MyEvent(BaseEvent):
+    event_type: str = "my.event"
+    data: str
+
+# Define your publisher
+class MyEventPublisher(BaseEventPublisher):
+    def service_name(self) -> str:
+        return "my_service"
+
+    async def publish_my_event(self, data: str) -> bool:
+        event = MyEvent(event_type="my.event", data=data)
+        return await self.publish_event(event, subject="my.event")
+```
+
+## Projects Using isA_common
+
+- **isA_user** - Microservices platform (17 services)
+- **isA_Model** - AI model inference service
+- **isA_Agent** - AI agent service
+- **isA_MCP** - Model Control Protocol service
+
+## Components
+
+### gRPC Clients (`grpc_clients/`)
+
+- `NATSClient` - NATS message bus client (port 50056)
+- `MinIOClient` - Object storage client (port 50051)
+- `MQTTClient` - MQTT broker client (port 50053)
+- `DuckDBClient` - Analytics database client (port 50052)
+- `SupabaseClient` - Supabase client (port 50057)
+
+### Event Framework (`grpc_clients/events/`)
+
+- `BaseEvent` - Base event model with metadata
+- `EventMetadata` - Standard event metadata
+- `BaseEventPublisher` - Base publisher class (abstract)
+- `BaseEventSubscriber` - Base subscriber class with idempotency
+- `EventHandler` - Event handler interface (abstract)
+- `IdempotencyChecker` - Duplicate prevention
+- `RetryPolicy` - Retry configuration
+
+## Development
+
+### Generating Proto Files
+
+Proto files are generated from the parent `isA_Cloud` project:
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud
+./scripts/generate-grpc.sh
+```
+
+This script generates:
+- Go proto files → `api/proto/*.pb.go`
+- Python proto files → `isA_common/grpc_clients/proto/*.py`
+
+### Running Tests
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+pytest tests/
+```
+
+## Package Structure
+
+```
+isA_Cloud/
+├── isA_common/                      # Python package
+│   ├── grpc_clients/
+│   │   ├── __init__.py
+│   │   ├── base_client.py
+│   │   ├── nats_client.py
+│   │   ├── minio_client.py
+│   │   ├── mqtt_client.py
+│   │   ├── duckdb_client.py
+│   │   ├── supabase_client.py
+│   │   ├── events/
+│   │   │   ├── __init__.py
+│   │   │   ├── base_event_models.py
+│   │   │   ├── base_event_publisher.py
+│   │   │   └── base_event_subscriber.py
+│   │   └── proto/
+│   │       ├── __init__.py
+│   │       ├── common_pb2.py
+│   │       ├── nats_service_pb2.py
+│   │       └── ...
+│   ├── setup.py
+│   ├── pyproject.toml
+│   ├── README.md
+│   └── requirements.txt
+├── scripts/
+│   └── generate-grpc.sh             # Generates to isA_common/
+└── api/proto/                       # Proto definitions
+```
+
+## Version
+
+Current version: **0.1.0**
+
+## License
+
+Proprietary - isA Platform

isa_common-0.1.0/README.md

@@ -0,0 +1,148 @@
+# isA Common
+
+Shared Python infrastructure library for the isA platform.
+
+## Overview
+
+This package provides common infrastructure components used across all isA Python services:
+- **gRPC Clients**: NATS, MinIO, MQTT, DuckDB, Supabase, etc.
+- **Event Framework**: Generic event-driven architecture base classes
+- **Proto Files**: Generated gRPC proto files
+
+## Installation
+
+### Development Install (Recommended)
+
+```bash
+pip install -e /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+```
+
+### From Source
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+pip install .
+```
+
+## Usage
+
+### gRPC Clients
+
+```python
+from grpc_clients import NATSClient, MinIOClient, get_client
+
+# Option 1: Direct instantiation
+nats = NATSClient(host='localhost', port=50056)
+
+# Option 2: Factory pattern
+nats = get_client('nats', user_id='my_service')
+```
+
+### Event Framework
+
+```python
+from grpc_clients.events import BaseEvent, BaseEventPublisher
+
+# Define your event
+class MyEvent(BaseEvent):
+    event_type: str = "my.event"
+    data: str
+
+# Define your publisher
+class MyEventPublisher(BaseEventPublisher):
+    def service_name(self) -> str:
+        return "my_service"
+
+    async def publish_my_event(self, data: str) -> bool:
+        event = MyEvent(event_type="my.event", data=data)
+        return await self.publish_event(event, subject="my.event")
+```
+
+## Projects Using isA_common
+
+- **isA_user** - Microservices platform (17 services)
+- **isA_Model** - AI model inference service
+- **isA_Agent** - AI agent service
+- **isA_MCP** - Model Control Protocol service
+
+## Components
+
+### gRPC Clients (`grpc_clients/`)
+
+- `NATSClient` - NATS message bus client (port 50056)
+- `MinIOClient` - Object storage client (port 50051)
+- `MQTTClient` - MQTT broker client (port 50053)
+- `DuckDBClient` - Analytics database client (port 50052)
+- `SupabaseClient` - Supabase client (port 50057)
+
+### Event Framework (`grpc_clients/events/`)
+
+- `BaseEvent` - Base event model with metadata
+- `EventMetadata` - Standard event metadata
+- `BaseEventPublisher` - Base publisher class (abstract)
+- `BaseEventSubscriber` - Base subscriber class with idempotency
+- `EventHandler` - Event handler interface (abstract)
+- `IdempotencyChecker` - Duplicate prevention
+- `RetryPolicy` - Retry configuration
+
+## Development
+
+### Generating Proto Files
+
+Proto files are generated from the parent `isA_Cloud` project:
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud
+./scripts/generate-grpc.sh
+```
+
+This script generates:
+- Go proto files → `api/proto/*.pb.go`
+- Python proto files → `isA_common/grpc_clients/proto/*.py`
+
+### Running Tests
+
+```bash
+cd /Users/xenodennis/Documents/Fun/isA_Cloud/isA_common
+pytest tests/
+```
+
+## Package Structure
+
+```
+isA_Cloud/
+├── isA_common/                      # Python package
+│   ├── grpc_clients/
+│   │   ├── __init__.py
+│   │   ├── base_client.py
+│   │   ├── nats_client.py
+│   │   ├── minio_client.py
+│   │   ├── mqtt_client.py
+│   │   ├── duckdb_client.py
+│   │   ├── supabase_client.py
+│   │   ├── events/
+│   │   │   ├── __init__.py
+│   │   │   ├── base_event_models.py
+│   │   │   ├── base_event_publisher.py
+│   │   │   └── base_event_subscriber.py
+│   │   └── proto/
+│   │       ├── __init__.py
+│   │       ├── common_pb2.py
+│   │       ├── nats_service_pb2.py
+│   │       └── ...
+│   ├── setup.py
+│   ├── pyproject.toml
+│   ├── README.md
+│   └── requirements.txt
+├── scripts/
+│   └── generate-grpc.sh             # Generates to isA_common/
+└── api/proto/                       # Proto definitions
+```
+
+## Version
+
+Current version: **0.1.0**
+
+## License
+
+Proprietary - isA Platform

isa_common-0.1.0/isa_common/__init__.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+gRPC Clients Package
+统一的 gRPC 客户端接口
+
+使用示例:
+    from core.clients import get_client, SupabaseClient, MinIOClient
+    
+    # 方式 1: 使用工厂函数
+    supabase = get_client('supabase', user_id='user_123')
+    
+    # 方式 2: 直接实例化
+    minio = MinIOClient(host='localhost', port=50051, user_id='user_123')
+    
+    # 方式 3: 使用 with 语句自动管理连接
+    with SupabaseClient() as client:
+        client.query('users', select='*')
+"""
+
+from typing import Optional, Dict
+from .base_client import BaseGRPCClient
+from .supabase_client import SupabaseClient
+from .minio_client import MinIOClient
+from .duckdb_client import DuckDBClient
+from .mqtt_client import MQTTClient
+from .nats_client import NATSClient
+
+# Import events module (but don't unpack, keep as submodule)
+from . import events
+
+# 导出所有客户端
+__all__ = [
+    'BaseGRPCClient',
+    'SupabaseClient',
+    'MinIOClient',
+    'DuckDBClient',
+    'MQTTClient',
+    'NATSClient',
+    'get_client',
+    'ClientFactory',
+    'events',  # Export events submodule
+]
+
+# 默认配置
+DEFAULT_PORTS: Dict[str, int] = {
+    'minio': 50051,
+    'duckdb': 50052,
+    'mqtt': 50053,
+    'loki': 50054,
+    'redis': 50055,
+    'nats': 50056,
+    'supabase': 50057,
+}
+
+DEFAULT_HOST = 'localhost'
+
+
+class ClientFactory:
+    """gRPC 客户端工厂"""
+    
+    # 客户端映射
+    _clients = {
+        'supabase': SupabaseClient,
+        'minio': MinIOClient,
+        'duckdb': DuckDBClient,
+        'mqtt': MQTTClient,
+        'nats': NATSClient,
+        # TODO: 添加其他客户端
+        # 'redis': RedisClient,
+        # 'loki': LokiClient,
+    }
+    
+    @classmethod
+    def create(cls, service_name: str, host: Optional[str] = None, 
+               port: Optional[int] = None, user_id: Optional[str] = None) -> BaseGRPCClient:
+        """
+        创建 gRPC 客户端
+        
+        Args:
+            service_name: 服务名称 (supabase, minio, duckdb, etc.)
+            host: 服务地址 (默认: localhost)
+            port: 服务端口 (默认: 根据服务自动选择)
+            user_id: 用户 ID
+        
+        Returns:
+            客户端实例
+        
+        Raises:
+            ValueError: 如果服务名称不支持
+        
+        示例:
+            client = ClientFactory.create('supabase', user_id='user_123')
+            client = ClientFactory.create('minio', host='192.168.1.100', port=50051)
+        """
+        service_name = service_name.lower()
+        
+        if service_name not in cls._clients:
+            available = ', '.join(cls._clients.keys())
+            raise ValueError(f"不支持的服务: {service_name}. 可用服务: {available}")
+        
+        # 使用默认值
+        if host is None:
+            host = DEFAULT_HOST
+        if port is None:
+            port = DEFAULT_PORTS.get(service_name, 50051)
+        
+        client_class = cls._clients[service_name]
+        return client_class(host=host, port=port, user_id=user_id)
+    
+    @classmethod
+    def register_client(cls, service_name: str, client_class):
+        """
+        注册新的客户端类
+        
+        Args:
+            service_name: 服务名称
+            client_class: 客户端类 (必须继承 BaseGRPCClient)
+        """
+        if not issubclass(client_class, BaseGRPCClient):
+            raise TypeError(f"{client_class} 必须继承 BaseGRPCClient")
+        
+        cls._clients[service_name.lower()] = client_class
+        print(f"✅ 注册客户端: {service_name} -> {client_class.__name__}")
+    
+    @classmethod
+    def list_services(cls) -> list:
+        """列出所有可用的服务"""
+        return list(cls._clients.keys())
+
+
+# 便捷函数
+def get_client(service_name: str, host: Optional[str] = None, 
+               port: Optional[int] = None, user_id: Optional[str] = None) -> BaseGRPCClient:
+    """
+    获取 gRPC 客户端 (便捷函数)
+    
+    Args:
+        service_name: 服务名称
+        host: 服务地址
+        port: 服务端口
+        user_id: 用户 ID
+    
+    Returns:
+        客户端实例
+    
+    示例:
+        from core.clients import get_client
+        
+        supabase = get_client('supabase', user_id='user_123')
+        minio = get_client('minio', host='192.168.1.100')
+    """
+    return ClientFactory.create(service_name, host, port, user_id)
+
+
+# 显示所有可用服务
+def show_available_services():
+    """显示所有可用的 gRPC 服务"""
+    print("📦 可用的 gRPC 服务:")
+    print()
+    for service in sorted(ClientFactory.list_services()):
+        port = DEFAULT_PORTS.get(service, 'N/A')
+        client_class = ClientFactory._clients[service]
+        print(f"  • {service:12} (端口: {port})  -> {client_class.__name__}")
+    print()
+
+
+if __name__ == '__main__':
+    # 显示可用服务
+    show_available_services()
+    
+    # 测试客户端创建
+    print("测试客户端创建:")
+    print("-" * 60)
+    
+    # 使用工厂创建客户端
+    with get_client('supabase', user_id='test_user') as supabase:
+        supabase.health_check()
+    
+    print()
+    
+    with get_client('minio', user_id='test_user') as minio:
+        minio.health_check()
+

isa_common-0.1.0/isa_common/base_client.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Base gRPC Client
+所有 gRPC 客户端的基类，提供统一的连接管理和错误处理
+"""
+
+import grpc
+import logging
+import threading
+from typing import Optional
+from abc import ABC, abstractmethod
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class BaseGRPCClient(ABC):
+    """gRPC 客户端基类"""
+
+    def __init__(self, host: str = 'localhost', port: int = 50051, user_id: Optional[str] = None,
+                 lazy_connect: bool = True, enable_compression: bool = True, enable_retry: bool = True):
+        """
+        初始化 gRPC 客户端
+
+        Args:
+            host: 服务地址
+            port: 服务端口
+            user_id: 用户 ID (用于多租户隔离)
+            lazy_connect: 是否延迟连接 (默认: True, 更快的启动速度)
+            enable_compression: 是否启用 gRPC 压缩 (默认: True)
+            enable_retry: 是否启用重试逻辑 (默认: True)
+        """
+        self.host = host
+        self.port = port
+        self.user_id = user_id or 'default_user'
+        self.address = f'{host}:{port}'
+        self.enable_compression = enable_compression
+        self.enable_retry = enable_retry
+
+        # Lazy initialization
+        self.channel = None
+        self.stub = None
+        self._connect_lock = threading.Lock()
+        self._connected = False
+
+        # Connect immediately if not lazy
+        if not lazy_connect:
+            self._ensure_connected()
+    
+    def _ensure_connected(self):
+        """确保已连接（线程安全的延迟连接）"""
+        if self._connected and self.channel is not None:
+            return
+
+        with self._connect_lock:
+            # Double-check after acquiring lock
+            if self._connected and self.channel is not None:
+                return
+
+            logger.info(f"[{self.service_name()}] Connecting to {self.address}...")
+
+            # Build channel options
+            options = [
+                ('grpc.max_receive_message_length', 100 * 1024 * 1024),  # 100MB
+                ('grpc.max_send_message_length', 100 * 1024 * 1024),     # 100MB
+                ('grpc.keepalive_time_ms', 10000),
+                ('grpc.keepalive_timeout_ms', 5000),
+            ]
+
+            # Add compression if enabled
+            if self.enable_compression:
+                options.append(('grpc.default_compression_algorithm', grpc.Compression.Gzip))
+                options.append(('grpc.default_compression_level', grpc.Compression.Gzip))
+
+            # Create channel
+            self.channel = grpc.insecure_channel(self.address, options=options)
+
+            # Create stub
+            self.stub = self._create_stub()
+
+            # Mark as connected
+            self._connected = True
+            logger.info(f"[{self.service_name()}] Connected successfully to {self.address}")
+
+    @abstractmethod
+    def _create_stub(self):
+        """子类实现：创建特定服务的 stub"""
+        pass
+
+    @abstractmethod
+    def service_name(self) -> str:
+        """子类实现：返回服务名称"""
+        pass
+
+    def _call_with_retry(self, func, *args, **kwargs):
+        """带重试的 RPC 调用"""
+        if not self.enable_retry:
+            return func(*args, **kwargs)
+
+        @retry(
+            stop=stop_after_attempt(3),
+            wait=wait_exponential(multiplier=1, min=1, max=10),
+            retry=retry_if_exception_type(grpc.RpcError),
+            reraise=True
+        )
+        def _retry_wrapper():
+            self._ensure_connected()
+            return func(*args, **kwargs)
+
+        try:
+            return _retry_wrapper()
+        except grpc.RpcError as e:
+            logger.error(f"[{self.service_name()}] RPC failed after retries: {e.code()} - {e.details()}")
+            raise
+
+    def handle_error(self, e: Exception, operation: str = "操作"):
+        """统一错误处理"""
+        logger.error(f"[{self.service_name()}] {operation} 失败:")
+        if isinstance(e, grpc.RpcError):
+            logger.error(f"  错误代码: {e.code()}")
+            logger.error(f"  错误详情: {e.details()}")
+        else:
+            logger.error(f"  错误: {e}")
+        return None
+    
+    def close(self):
+        """关闭连接"""
+        if self.channel is not None:
+            self.channel.close()
+            self._connected = False
+            logger.info(f"[{self.service_name()}] Connection closed")
+    
+    def __enter__(self):
+        """支持 with 语句"""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """退出时自动关闭连接"""
+        self.close()
+