cognitive-modules 0.6.1__py3-none-any.whl → 2.2.1__py3-none-any.whl

cognitive/runner.py

@@ -10,13 +10,8 @@ v2.2 Features:
 """
 
 import json
-import base64
-import mimetypes
 from pathlib import Path
-from typing import Optional, TypedDict, Union, Literal, Callable, AsyncIterator
-from dataclasses import dataclass, field
-from urllib.request import urlopen
-from urllib.error import URLError
+from typing import Optional, TypedDict, Union, Literal
 
 import jsonschema
 import yaml
@@ -657,692 +652,3 @@ def should_escalate(result: EnvelopeResponseV22, confidence_threshold: float = 0
         return True
     
     return False
-
-
-# =============================================================================
-# v2.5 Streaming Support
-# =============================================================================
-
-import uuid
-from typing import AsyncIterator, Iterator, Any, Callable
-from dataclasses import dataclass, field
-
-
-@dataclass
-class StreamingSession:
-    """Represents an active streaming session."""
-    session_id: str
-    module_name: str
-    started_at: float = field(default_factory=lambda: __import__('time').time())
-    chunks_sent: int = 0
-    accumulated_data: dict = field(default_factory=dict)
-    accumulated_text: dict = field(default_factory=dict)  # field -> accumulated string
-
-
-def create_session_id() -> str:
-    """Generate a unique session ID for streaming."""
-    return f"sess_{uuid.uuid4().hex[:12]}"
-
-
-def create_meta_chunk(session_id: str, initial_risk: str = "low") -> dict:
-    """Create the initial meta chunk for streaming."""
-    return {
-        "ok": True,
-        "streaming": True,
-        "session_id": session_id,
-        "meta": {
-            "confidence": None,
-            "risk": initial_risk,
-            "explain": "Processing..."
-        }
-    }
-
-
-def create_delta_chunk(seq: int, field: str, delta: str) -> dict:
-    """Create a delta chunk for incremental content."""
-    return {
-        "chunk": {
-            "seq": seq,
-            "type": "delta",
-            "field": field,
-            "delta": delta
-        }
-    }
-
-
-def create_snapshot_chunk(seq: int, field: str, data: Any) -> dict:
-    """Create a snapshot chunk for full field replacement."""
-    return {
-        "chunk": {
-            "seq": seq,
-            "type": "snapshot",
-            "field": field,
-            "data": data
-        }
-    }
-
-
-def create_progress_chunk(percent: int, stage: str = "", message: str = "") -> dict:
-    """Create a progress update chunk."""
-    return {
-        "progress": {
-            "percent": percent,
-            "stage": stage,
-            "message": message
-        }
-    }
-
-
-def create_final_chunk(meta: dict, data: dict, usage: dict = None) -> dict:
-    """Create the final chunk with complete data."""
-    chunk = {
-        "final": True,
-        "meta": meta,
-        "data": data
-    }
-    if usage:
-        chunk["usage"] = usage
-    return chunk
-
-
-def create_error_chunk(session_id: str, error_code: str, message: str, 
-                       recoverable: bool = False, partial_data: dict = None) -> dict:
-    """Create an error chunk for stream failures."""
-    chunk = {
-        "ok": False,
-        "streaming": True,
-        "session_id": session_id,
-        "error": {
-            "code": error_code,
-            "message": message,
-            "recoverable": recoverable
-        }
-    }
-    if partial_data:
-        chunk["partial_data"] = partial_data
-    return chunk
-
-
-def assemble_streamed_data(session: StreamingSession) -> dict:
-    """Assemble accumulated streaming data into final format."""
-    data = session.accumulated_data.copy()
-    
-    # Merge accumulated text fields
-    for field_path, text in session.accumulated_text.items():
-        parts = field_path.split(".")
-        target = data
-        for part in parts[:-1]:
-            if part not in target:
-                target[part] = {}
-            target = target[part]
-        target[parts[-1]] = text
-    
-    return data
-
-
-class StreamingRunner:
-    """Runner with streaming support for v2.5 modules."""
-    
-    def __init__(self, provider_callback: Callable = None):
-        """
-        Initialize streaming runner.
-        
-        Args:
-            provider_callback: Function to call LLM with streaming support.
-                              Signature: async (prompt, images=None) -> AsyncIterator[str]
-        """
-        self.provider_callback = provider_callback or self._default_provider
-        self.active_sessions: dict[str, StreamingSession] = {}
-    
-    async def _default_provider(self, prompt: str, images: list = None) -> AsyncIterator[str]:
-        """Default provider - yields entire response at once (for testing)."""
-        # In real implementation, this would stream from LLM
-        yield '{"ok": true, "meta": {"confidence": 0.9, "risk": "low", "explain": "Test"}, "data": {"rationale": "Test response"}}'
-    
-    async def execute_stream(
-        self,
-        module_name: str,
-        input_data: dict,
-        on_chunk: Callable[[dict], None] = None
-    ) -> AsyncIterator[dict]:
-        """
-        Execute a module with streaming output.
-        
-        Args:
-            module_name: Name of the module to execute
-            input_data: Input data including multimodal content
-            on_chunk: Optional callback for each chunk
-        
-        Yields:
-            Streaming chunks (meta, delta, progress, final, or error)
-        """
-        session_id = create_session_id()
-        session = StreamingSession(session_id=session_id, module_name=module_name)
-        self.active_sessions[session_id] = session
-        
-        try:
-            # Load module
-            module = load_module(module_name)
-            
-            # Check if module supports streaming
-            response_config = module.get("response", {})
-            mode = response_config.get("mode", "sync")
-            if mode not in ("streaming", "both"):
-                # Fall back to sync execution
-                result = await self._execute_sync(module, input_data)
-                yield create_meta_chunk(session_id)
-                yield create_final_chunk(result["meta"], result["data"])
-                return
-            
-            # Extract images for multimodal
-            images = self._extract_media(input_data)
-            
-            # Build prompt
-            prompt = self._build_prompt(module, input_data)
-            
-            # Send initial meta chunk
-            meta_chunk = create_meta_chunk(session_id)
-            if on_chunk:
-                on_chunk(meta_chunk)
-            yield meta_chunk
-            
-            # Stream from LLM
-            seq = 1
-            accumulated_response = ""
-            
-            async for text_chunk in self.provider_callback(prompt, images):
-                accumulated_response += text_chunk
-                
-                # Create delta chunk for rationale field
-                delta_chunk = create_delta_chunk(seq, "data.rationale", text_chunk)
-                session.chunks_sent += 1
-                session.accumulated_text.setdefault("data.rationale", "")
-                session.accumulated_text["data.rationale"] += text_chunk
-                
-                if on_chunk:
-                    on_chunk(delta_chunk)
-                yield delta_chunk
-                seq += 1
-            
-            # Parse final response
-            try:
-                final_data = parse_llm_response(accumulated_response)
-                final_data = repair_envelope(final_data)
-            except Exception as e:
-                error_chunk = create_error_chunk(
-                    session_id, "E2001", str(e), 
-                    recoverable=False,
-                    partial_data={"rationale": session.accumulated_text.get("data.rationale", "")}
-                )
-                yield error_chunk
-                return
-            
-            # Send final chunk
-            final_chunk = create_final_chunk(
-                final_data.get("meta", {}),
-                final_data.get("data", {}),
-                {"input_tokens": 0, "output_tokens": seq}  # Placeholder
-            )
-            if on_chunk:
-                on_chunk(final_chunk)
-            yield final_chunk
-            
-        except Exception as e:
-            error_chunk = create_error_chunk(
-                session_id, "E2010", f"Stream error: {str(e)}",
-                recoverable=False
-            )
-            yield error_chunk
-        finally:
-            del self.active_sessions[session_id]
-    
-    async def _execute_sync(self, module: dict, input_data: dict) -> dict:
-        """Execute module synchronously (fallback)."""
-        # Use existing sync execution
-        return run_module(module["name"], input_data)
-    
-    def _build_prompt(self, module: dict, input_data: dict) -> str:
-        """Build prompt from module and input."""
-        prompt_template = module.get("prompt", "")
-        return substitute_arguments(prompt_template, input_data)
-    
-    def _extract_media(self, input_data: dict) -> list:
-        """Extract media inputs from input data."""
-        images = input_data.get("images", [])
-        audio = input_data.get("audio", [])
-        video = input_data.get("video", [])
-        return images + audio + video
-
-
-# =============================================================================
-# v2.5 Multimodal Support
-# =============================================================================
-
-SUPPORTED_IMAGE_TYPES = {
-    "image/jpeg", "image/png", "image/webp", "image/gif"
-}
-
-SUPPORTED_AUDIO_TYPES = {
-    "audio/mpeg", "audio/wav", "audio/ogg", "audio/webm"
-}
-
-SUPPORTED_VIDEO_TYPES = {
-    "video/mp4", "video/webm", "video/quicktime"
-}
-
-# Magic bytes for media type detection
-MEDIA_MAGIC_BYTES = {
-    "image/jpeg": [b"\xff\xd8\xff"],
-    "image/png": [b"\x89PNG\r\n\x1a\n"],
-    "image/gif": [b"GIF87a", b"GIF89a"],
-    "image/webp": [b"RIFF"],  # Check WEBP signature later
-    "audio/mpeg": [b"\xff\xfb", b"\xff\xfa", b"ID3"],
-    "audio/wav": [b"RIFF"],  # Check WAVE signature later
-    "audio/ogg": [b"OggS"],
-    "video/mp4": [b"\x00\x00\x00"],  # ftyp check needed
-    "video/webm": [b"\x1a\x45\xdf\xa3"],
-    "application/pdf": [b"%PDF"],
-}
-
-# Media size limits in bytes
-MEDIA_SIZE_LIMITS = {
-    "image": 20 * 1024 * 1024,   # 20MB
-    "audio": 25 * 1024 * 1024,   # 25MB
-    "video": 100 * 1024 * 1024,  # 100MB
-    "document": 50 * 1024 * 1024,  # 50MB
-}
-
-# Media dimension limits
-MEDIA_DIMENSION_LIMITS = {
-    "max_width": 8192,
-    "max_height": 8192,
-    "min_width": 10,
-    "min_height": 10,
-    "max_pixels": 67108864,  # 8192 x 8192
-}
-
-# v2.5 Error codes
-ERROR_CODES_V25 = {
-    "UNSUPPORTED_MEDIA_TYPE": "E1010",
-    "MEDIA_TOO_LARGE": "E1011",
-    "MEDIA_FETCH_FAILED": "E1012",
-    "MEDIA_DECODE_FAILED": "E1013",
-    "MEDIA_TYPE_MISMATCH": "E1014",
-    "MEDIA_DIMENSION_EXCEEDED": "E1015",
-    "MEDIA_DIMENSION_TOO_SMALL": "E1016",
-    "MEDIA_PIXEL_LIMIT": "E1017",
-    "UPLOAD_EXPIRED": "E1018",
-    "UPLOAD_NOT_FOUND": "E1019",
-    "CHECKSUM_MISMATCH": "E1020",
-    "STREAM_INTERRUPTED": "E2010",
-    "STREAM_TIMEOUT": "E2011",
-    "STREAMING_NOT_SUPPORTED": "E4010",
-    "MULTIMODAL_NOT_SUPPORTED": "E4011",
-    "RECOVERY_NOT_SUPPORTED": "E4012",
-    "SESSION_EXPIRED": "E4013",
-    "CHECKPOINT_INVALID": "E4014",
-}
-
-
-def detect_media_type_from_magic(data: bytes) -> Optional[str]:
-    """Detect media type from magic bytes."""
-    for mime_type, magic_list in MEDIA_MAGIC_BYTES.items():
-        for magic in magic_list:
-            if data.startswith(magic):
-                # Special handling for RIFF-based formats
-                if magic == b"RIFF" and len(data) >= 12:
-                    if data[8:12] == b"WEBP":
-                        return "image/webp"
-                    elif data[8:12] == b"WAVE":
-                        return "audio/wav"
-                    continue
-                # Special handling for MP4 (check for ftyp)
-                if mime_type == "video/mp4" and len(data) >= 8:
-                    if b"ftyp" in data[4:8]:
-                        return "video/mp4"
-                    continue
-                return mime_type
-    return None
-
-
-def validate_media_magic_bytes(data: bytes, declared_type: str) -> tuple[bool, str]:
-    """
-    Validate that media content matches declared MIME type.
-    
-    Returns:
-        Tuple of (is_valid, error_message)
-    """
-    detected_type = detect_media_type_from_magic(data)
-    
-    if detected_type is None:
-        return True, ""  # Can't detect, assume valid
-    
-    # Normalize types for comparison
-    declared_category = declared_type.split("/")[0]
-    detected_category = detected_type.split("/")[0]
-    
-    if declared_category != detected_category:
-        return False, f"Media content mismatch: declared {declared_type}, detected {detected_type}"
-    
-    return True, ""
-
-
-def validate_image_dimensions(data: bytes) -> Optional[tuple]:
-    """
-    Extract image dimensions from raw bytes.
-    
-    Returns:
-        Tuple of (width, height) or None if cannot determine.
-    """
-    try:
-        # PNG dimensions at bytes 16-24
-        if data.startswith(b"\x89PNG"):
-            width = int.from_bytes(data[16:20], "big")
-            height = int.from_bytes(data[20:24], "big")
-            return (width, height)
-        
-        # JPEG - need to parse markers
-        if data.startswith(b"\xff\xd8"):
-            i = 2
-            while i < len(data) - 8:
-                if data[i] != 0xff:
-                    break
-                marker = data[i + 1]
-                if marker in (0xc0, 0xc1, 0xc2):  # SOF markers
-                    height = int.from_bytes(data[i + 5:i + 7], "big")
-                    width = int.from_bytes(data[i + 7:i + 9], "big")
-                    return (width, height)
-                length = int.from_bytes(data[i + 2:i + 4], "big")
-                i += 2 + length
-        
-        # GIF dimensions at bytes 6-10
-        if data.startswith(b"GIF"):
-            width = int.from_bytes(data[6:8], "little")
-            height = int.from_bytes(data[8:10], "little")
-            return (width, height)
-        
-    except Exception:
-        pass
-    
-    return None
-
-
-def validate_media_input(media: dict, constraints: dict = None) -> tuple:
-    """
-    Validate a media input object with enhanced v2.5 validation.
-    
-    Returns:
-        Tuple of (is_valid, error_message, error_code)
-    """
-    constraints = constraints or {}
-    
-    media_type = media.get("type")
-    if media_type not in ("url", "base64", "file", "upload_ref"):
-        return False, "Invalid media type. Must be url, base64, file, or upload_ref", None
-    
-    if media_type == "url":
-        url = media.get("url")
-        if not url:
-            return False, "URL media missing 'url' field", None
-        if not url.startswith(("http://", "https://")):
-            return False, "URL must start with http:// or https://", None
-    
-    elif media_type == "base64":
-        mime_type = media.get("media_type")
-        if not mime_type:
-            return False, "Base64 media missing 'media_type' field", None
-        data = media.get("data")
-        if not data:
-            return False, "Base64 media missing 'data' field", None
-        
-        # Validate base64 and decode
-        try:
-            decoded = base64.b64decode(data)
-        except Exception:
-            return False, "Invalid base64 encoding", ERROR_CODES_V25["MEDIA_DECODE_FAILED"]
-        
-        # Check size
-        category = mime_type.split("/")[0]
-        max_size = constraints.get("max_size_bytes", MEDIA_SIZE_LIMITS.get(category, 20 * 1024 * 1024))
-        if len(decoded) > max_size:
-            return False, f"Media exceeds size limit ({len(decoded)} > {max_size} bytes)", ERROR_CODES_V25["MEDIA_TOO_LARGE"]
-        
-        # Validate magic bytes
-        is_valid, error = validate_media_magic_bytes(decoded, mime_type)
-        if not is_valid:
-            return False, error, ERROR_CODES_V25["MEDIA_TYPE_MISMATCH"]
-        
-        # Validate image dimensions if applicable
-        if category == "image":
-            dimensions = validate_image_dimensions(decoded)
-            if dimensions:
-                width, height = dimensions
-                limits = MEDIA_DIMENSION_LIMITS
-                
-                if width > limits["max_width"] or height > limits["max_height"]:
-                    return False, f"Image dimensions ({width}x{height}) exceed maximum ({limits['max_width']}x{limits['max_height']})", ERROR_CODES_V25["MEDIA_DIMENSION_EXCEEDED"]
-                
-                if width < limits["min_width"] or height < limits["min_height"]:
-                    return False, f"Image dimensions ({width}x{height}) below minimum ({limits['min_width']}x{limits['min_height']})", ERROR_CODES_V25["MEDIA_DIMENSION_TOO_SMALL"]
-                
-                if width * height > limits["max_pixels"]:
-                    return False, f"Image pixel count ({width * height}) exceeds maximum ({limits['max_pixels']})", ERROR_CODES_V25["MEDIA_PIXEL_LIMIT"]
-        
-        # Validate checksum if provided
-        checksum = media.get("checksum")
-        if checksum:
-            import hashlib
-            algorithm = checksum.get("algorithm", "sha256")
-            expected = checksum.get("value", "")
-            
-            if algorithm == "sha256":
-                actual = hashlib.sha256(decoded).hexdigest()
-            elif algorithm == "md5":
-                actual = hashlib.md5(decoded).hexdigest()
-            elif algorithm == "crc32":
-                import zlib
-                actual = format(zlib.crc32(decoded) & 0xffffffff, '08x')
-            else:
-                return False, f"Unsupported checksum algorithm: {algorithm}", None
-            
-            if actual.lower() != expected.lower():
-                return False, f"Checksum mismatch: expected {expected}, got {actual}", ERROR_CODES_V25["CHECKSUM_MISMATCH"]
-    
-    elif media_type == "file":
-        path = media.get("path")
-        if not path:
-            return False, "File media missing 'path' field", None
-        if not Path(path).exists():
-            return False, f"File not found: {path}", None
-        
-        # Check file size
-        file_size = Path(path).stat().st_size
-        mime, _ = mimetypes.guess_type(str(path))
-        if mime:
-            category = mime.split("/")[0]
-            max_size = constraints.get("max_size_bytes", MEDIA_SIZE_LIMITS.get(category, 20 * 1024 * 1024))
-            if file_size > max_size:
-                return False, f"File exceeds size limit ({file_size} > {max_size} bytes)", ERROR_CODES_V25["MEDIA_TOO_LARGE"]
-    
-    elif media_type == "upload_ref":
-        upload_id = media.get("upload_id")
-        if not upload_id:
-            return False, "Upload reference missing 'upload_id' field", None
-        # Note: Actual upload validation would require backend lookup
-    
-    return True, "", None
-
-
-def load_media_as_base64(media: dict) -> tuple[str, str]:
-    """
-    Load media from any source and return as base64.
-    
-    Returns:
-        Tuple of (base64_data, media_type)
-    """
-    media_type = media.get("type")
-    
-    if media_type == "base64":
-        return media["data"], media["media_type"]
-    
-    elif media_type == "url":
-        url = media["url"]
-        try:
-            with urlopen(url, timeout=30) as response:
-                data = response.read()
-                content_type = response.headers.get("Content-Type", "application/octet-stream")
-                # Extract just the mime type (remove charset etc)
-                content_type = content_type.split(";")[0].strip()
-                return base64.b64encode(data).decode("utf-8"), content_type
-        except URLError as e:
-            raise ValueError(f"Failed to fetch media from URL: {e}")
-    
-    elif media_type == "file":
-        path = Path(media["path"])
-        if not path.exists():
-            raise ValueError(f"File not found: {path}")
-        
-        mime_type, _ = mimetypes.guess_type(str(path))
-        mime_type = mime_type or "application/octet-stream"
-        
-        with open(path, "rb") as f:
-            data = f.read()
-        
-        return base64.b64encode(data).decode("utf-8"), mime_type
-    
-    raise ValueError(f"Unknown media type: {media_type}")
-
-
-def prepare_media_for_llm(media_list: list, provider: str = "openai") -> list:
-    """
-    Prepare media inputs for specific LLM provider format.
-    
-    Different providers have different multimodal input formats:
-    - OpenAI: {"type": "image_url", "image_url": {"url": "data:..."}}
-    - Anthropic: {"type": "image", "source": {"type": "base64", ...}}
-    - Google: {"inlineData": {"mimeType": "...", "data": "..."}}
-    """
-    prepared = []
-    
-    for media in media_list:
-        data, mime_type = load_media_as_base64(media)
-        
-        if provider == "openai":
-            prepared.append({
-                "type": "image_url",
-                "image_url": {
-                    "url": f"data:{mime_type};base64,{data}"
-                }
-            })
-        elif provider == "anthropic":
-            prepared.append({
-                "type": "image",
-                "source": {
-                    "type": "base64",
-                    "media_type": mime_type,
-                    "data": data
-                }
-            })
-        elif provider == "google":
-            prepared.append({
-                "inlineData": {
-                    "mimeType": mime_type,
-                    "data": data
-                }
-            })
-        else:
-            # Generic format
-            prepared.append({
-                "type": "base64",
-                "media_type": mime_type,
-                "data": data
-            })
-    
-    return prepared
-
-
-def get_modalities_config(module: dict) -> dict:
-    """Get modalities configuration from module."""
-    return module.get("modalities", {
-        "input": ["text"],
-        "output": ["text"]
-    })
-
-
-def supports_multimodal_input(module: dict) -> bool:
-    """Check if module supports multimodal input."""
-    modalities = get_modalities_config(module)
-    input_modalities = modalities.get("input", ["text"])
-    return any(m in input_modalities for m in ["image", "audio", "video"])
-
-
-def supports_multimodal_output(module: dict) -> bool:
-    """Check if module supports multimodal output."""
-    modalities = get_modalities_config(module)
-    output_modalities = modalities.get("output", ["text"])
-    return any(m in output_modalities for m in ["image", "audio", "video"])
-
-
-def validate_multimodal_input(input_data: dict, module: dict) -> tuple[bool, list[str]]:
-    """
-    Validate multimodal input against module configuration.
-    
-    Returns:
-        Tuple of (is_valid, list of errors)
-    """
-    errors = []
-    modalities = get_modalities_config(module)
-    input_modalities = set(modalities.get("input", ["text"]))
-    constraints = modalities.get("constraints", {})
-    
-    # Check images
-    images = input_data.get("images", [])
-    if images:
-        if "image" not in input_modalities:
-            errors.append("Module does not support image input")
-        else:
-            max_images = constraints.get("max_images", 10)
-            if len(images) > max_images:
-                errors.append(f"Too many images ({len(images)} > {max_images})")
-            
-            for i, img in enumerate(images):
-                valid, err, err_code = validate_media_input(img, constraints)
-                if not valid:
-                    errors.append(f"Image {i}: {err}" + (f" [{err_code}]" if err_code else ""))
-    
-    # Check audio
-    audio = input_data.get("audio", [])
-    if audio:
-        if "audio" not in input_modalities:
-            errors.append("Module does not support audio input")
-    
-    # Check video
-    video = input_data.get("video", [])
-    if video:
-        if "video" not in input_modalities:
-            errors.append("Module does not support video input")
-    
-    return len(errors) == 0, errors
-
-
-# =============================================================================
-# v2.5 Runtime Capabilities
-# =============================================================================
-
-def get_runtime_capabilities() -> dict:
-    """Get runtime capabilities for v2.5."""
-    return {
-        "runtime": "cognitive-runtime-python",
-        "version": "2.5.0",
-        "spec_version": "2.5",
-        "capabilities": {
-            "streaming": True,
-            "multimodal": {
-                "input": ["image"],  # Basic image support
-                "output": []  # No generation yet
-            },
-            "max_media_size_mb": 20,
-            "supported_transports": ["ndjson"],  # SSE requires async server
-            "conformance_level": 4
-        }
-    }

{cognitive_modules-0.6.1.dist-info → cognitive_modules-2.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognitive-modules
-Version: 0.6.1
+Version: 2.2.1
 Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
 Author: ziel-io
 License: MIT
@@ -69,32 +69,6 @@ English | [中文](README_zh.md)
 
 Cognitive Modules is an AI task definition specification designed for generation tasks that require **strong constraints, verifiability, and auditability**.
 
-## What's New in v2.5
-
-| Feature | Description |
-|---------|-------------|
-| **Streaming Response** | Real-time chunk-based output for better UX |
-| **Multimodal Support** | Native image, audio, and video input/output |
-| **Backward Compatible** | v2.2 modules run without modification |
-| **Level 4 Conformance** | Extended conformance level for v2.5 features |
-
-```yaml
-# module.yaml - v2.5 example
-name: image-analyzer
-version: 2.5.0
-tier: decision
-
-# v2.5: Enable streaming
-response:
-  mode: streaming
-  chunk_type: delta
-
-# v2.5: Enable multimodal
-modalities:
-  input: [text, image]
-  output: [text]
-```
-
 ## What's New in v2.2
 
 | Feature | Description |
@@ -114,7 +88,24 @@ modalities:
 - **Subagent Orchestration** - `@call:module` supports inter-module calls
 - **Parameter Passing** - `$ARGUMENTS` runtime substitution
 - **Multi-LLM Support** - OpenAI / Anthropic / MiniMax / Ollama
-- **Public Registry** - `cogn install registry:module-name`
+- **Public Registry** - `cog install registry:module-name`
+
+## Version Selection
+
+| Version | Spec | npm | PyPI | Status |
+|---------|------|-----|------|--------|
+| **v2.2** | v2.2 | `2.2.0` | `2.2.0` | ✅ Stable (recommended) |
+| **v2.5** | v2.5 | `2.5.0-beta.x` | `2.5.0bx` | 🧪 Beta (streaming + multimodal) |
+
+```bash
+# Install stable v2.2
+npm install cognitive-modules-cli@2.2.0
+pip install cognitive-modules==2.2.0
+
+# Install beta v2.5 (streaming + multimodal)
+npm install cognitive-modules-cli@beta
+pip install cognitive-modules==2.5.0b1
+```
 
 ## Installation
 
@@ -122,30 +113,27 @@ modalities:
 
 ```bash
 # Zero-install quick start (recommended)
-npx cogn run code-reviewer --args "your code"
+npx cognitive-modules-cli@2.2.0 run code-reviewer --args "your code"
 
 # Global installation
-npm install -g cogn
-
-# Or install with full package name
-npm install -g cognitive-modules-cli
+npm install -g cognitive-modules-cli@2.2.0
 ```
 
 ### Python (pip)
 
 ```bash
-pip install cognitive-modules
+pip install cognitive-modules==2.2.0
 
 # With LLM support
-pip install cognitive-modules[openai]      # OpenAI
-pip install cognitive-modules[anthropic]   # Claude
-pip install cognitive-modules[all]         # All providers
+pip install "cognitive-modules[openai]==2.2.0"      # OpenAI
+pip install "cognitive-modules[anthropic]==2.2.0"   # Claude
+pip install "cognitive-modules[all]==2.2.0"         # All providers
 ```
 
 | Platform | Package | Command | Features |
 |----------|---------|---------|----------|
-| **npm** | `cogn` | `cog` | ✅ Recommended, zero-install, full features |
-| pip | `cognitive-modules` | `cogn` | ✅ Full features |
+| **npm** | `cognitive-modules-cli` | `cog` | ✅ Recommended, zero-install, full features |
+| pip | `cognitive-modules` | `cog` | ✅ Full features |
 
 ## Quick Start
 
@@ -155,7 +143,7 @@ export LLM_PROVIDER=openai
 export OPENAI_API_KEY=sk-xxx
 
 # Run code review (npm)
-npx cogn run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
+npx cognitive-modules-cli run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
 
 # Or use globally installed cog command
 cog run code-reviewer --args "..." --pretty
@@ -221,70 +209,70 @@ All modules now return the unified v2.2 envelope format:
 | **Risk Aggregation** | `meta.risk = max(changes[*].risk)` |
 | **Parameter Passing** | `$ARGUMENTS` runtime substitution |
 | **Subagents** | `@call:module` for inter-module calls |
-| **Validation Tools** | `cogn validate` / `cogn validate --v22` |
+| **Validation Tools** | `cog validate` / `cog validate --v22` |
 
 ## Integration Methods
 
 | Method | Command | Use Case |
 |--------|---------|----------|
-| CLI | `cogn run` | Command line |
-| HTTP API | `cogn serve` | n8n, Coze, Dify |
-| MCP Server | `cogn mcp` | Claude, Cursor |
+| CLI | `cog run` | Command line |
+| HTTP API | `cog serve` | n8n, Coze, Dify |
+| MCP Server | `cog mcp` | Claude, Cursor |
 
 ## CLI Commands
 
 ```bash
 # Module management
-cogn list                    # List installed modules
-cogn info <module>           # View module details
-cogn validate <module>       # Validate module structure
-cogn validate <module> --v22 # Validate v2.2 format
+cog list                    # List installed modules
+cog info <module>           # View module details
+cog validate <module>       # Validate module structure
+cog validate <module> --v22 # Validate v2.2 format
 
 # Run modules
-cogn run <module> input.json -o output.json --pretty
-cogn run <module> --args "requirements" --pretty
-cogn run <module> --args "requirements" --subagent  # Enable subagent
+cog run <module> input.json -o output.json --pretty
+cog run <module> --args "requirements" --pretty
+cog run <module> --args "requirements" --subagent  # Enable subagent
 
 # Create modules
-cogn init <name> -d "description"
-cogn init <name> --format v22  # Create v2.2 format module
+cog init <name> -d "description"
+cog init <name> --format v22  # Create v2.2 format module
 
 # Migrate modules
-cogn migrate <module>        # Migrate v1/v2.1 module to v2.2
+cog migrate <module>        # Migrate v1/v2.1 module to v2.2
 
 # Install from GitHub (recommended)
-cogn add ziel-io/cognitive-modules -m code-simplifier
-cogn add org/repo -m module-name --tag v1.0.0   # Install specific version
-cogn remove <module>                             # Remove module
+cog add ziel-io/cognitive-modules -m code-simplifier
+cog add org/repo -m module-name --tag v1.0.0   # Install specific version
+cog remove <module>                             # Remove module
 
 # Version management
-cogn update <module>                 # Update to latest version
-cogn update <module> --tag v2.0.0    # Update to specific version
-cogn versions <url>                  # View available versions
+cog update <module>                 # Update to latest version
+cog update <module> --tag v2.0.0    # Update to specific version
+cog versions <url>                  # View available versions
 
 # Other installation methods
-cogn install github:user/repo/path
-cogn install registry:module-name
-cogn uninstall <module>
+cog install github:user/repo/path
+cog install registry:module-name
+cog uninstall <module>
 
 # Registry
-cogn registry                # View public modules
-cogn search <query>          # Search modules
+cog registry                # View public modules
+cog search <query>          # Search modules
 
 # Environment check
-cogn doctor
+cog doctor
 ```
 
 ## Built-in Modules
 
 | Module | Tier | Function | Example |
 |--------|------|----------|---------|
-| `code-reviewer` | decision | Code review | `cogn run code-reviewer --args "your code"` |
-| `code-simplifier` | decision | Code simplification | `cogn run code-simplifier --args "complex code"` |
-| `task-prioritizer` | decision | Task priority sorting | `cogn run task-prioritizer --args "task1,task2"` |
-| `api-designer` | decision | REST API design | `cogn run api-designer --args "order system"` |
-| `ui-spec-generator` | exploration | UI spec generation | `cogn run ui-spec-generator --args "e-commerce homepage"` |
-| `product-analyzer` | exploration | Product analysis (subagent) | `cogn run product-analyzer --args "health product" -s` |
+| `code-reviewer` | decision | Code review | `cog run code-reviewer --args "your code"` |
+| `code-simplifier` | decision | Code simplification | `cog run code-simplifier --args "complex code"` |
+| `task-prioritizer` | decision | Task priority sorting | `cog run task-prioritizer --args "task1,task2"` |
+| `api-designer` | decision | REST API design | `cog run api-designer --args "order system"` |
+| `ui-spec-generator` | exploration | UI spec generation | `cog run ui-spec-generator --args "e-commerce homepage"` |
+| `product-analyzer` | exploration | Product analysis (subagent) | `cog run product-analyzer --args "health product" -s` |
 
 ## Module Format
 
@@ -355,83 +343,6 @@ my-module/
 | `decision` | Judgment/evaluation/classification | medium | Enabled |
 | `exploration` | Exploration/research/inspiration | low | Enabled |
 
-## v2.5 Streaming & Multimodal
-
-### Streaming Response
-
-Enable real-time streaming for better UX:
-
-```yaml
-# module.yaml
-response:
-  mode: streaming      # sync | streaming | both
-  chunk_type: delta    # delta | snapshot
-```
-
-**JavaScript/TypeScript Usage:**
-
-```typescript
-import { runModuleStream } from 'cognitive-modules-cli';
-
-// Stream execution
-for await (const chunk of runModuleStream(module, provider, { input })) {
-  if ('delta' in chunk.chunk) {
-    process.stdout.write(chunk.chunk.delta);
-  } else if ('final' in chunk) {
-    console.log('\nComplete:', chunk.data);
-  }
-}
-```
-
-**Python Usage:**
-
-```python
-from cognitive import StreamingRunner
-
-runner = StreamingRunner()
-async for chunk in runner.execute_stream("image-analyzer", input_data):
-    if chunk.get("chunk"):
-        print(chunk["chunk"]["delta"], end="")
-    elif chunk.get("final"):
-        print("\nComplete:", chunk["data"])
-```
-
-### Multimodal Input
-
-Enable image/audio/video processing:
-
-```yaml
-# module.yaml
-modalities:
-  input: [text, image, audio]
-  output: [text, image]
-```
-
-**JavaScript/TypeScript Usage:**
-
-```typescript
-const result = await runModule(module, provider, {
-  input: {
-    prompt: "Describe this image",
-    images: [
-      { type: "url", url: "https://example.com/image.jpg" },
-      { type: "base64", media_type: "image/png", data: "iVBORw0K..." }
-    ]
-  }
-});
-```
-
-**Python Usage:**
-
-```python
-result = await runner.execute("image-analyzer", {
-    "prompt": "Describe this image",
-    "images": [
-        {"type": "url", "url": "https://example.com/image.jpg"},
-        {"type": "file", "path": "./local-image.png"}
-    ]
-})
-
 ## Using with AI Tools
 
 ### Cursor / Codex CLI
@@ -473,7 +384,7 @@ export MINIMAX_API_KEY=sk-xxx
 export LLM_PROVIDER=ollama
 
 # Check configuration
-cogn doctor
+cog doctor
 ```
 
 ## Migrating to v2.2
@@ -482,13 +393,13 @@ Migrate from v1 or v2.1 modules to v2.2:
 
 ```bash
 # Auto-migrate single module
-cogn migrate code-reviewer
+cog migrate code-reviewer
 
 # Migrate all modules
-cogn migrate --all
+cog migrate --all
 
 # Verify migration result
-cogn validate code-reviewer --v22
+cog validate code-reviewer --v22
 ```
 
 Manual migration steps:
@@ -511,8 +422,8 @@ pip install -e ".[dev]"
 pytest tests/ -v
 
 # Create new module (v2.2 format)
-cogn init my-module -d "module description" --format v22
-cogn validate my-module --v22
+cog init my-module -d "module description" --format v22
+cog validate my-module --v22
 ```
 
 ## Project Structure
@@ -546,8 +457,8 @@ cognitive-modules/
 
 | Platform | Package | Command | Installation |
 |----------|---------|---------|--------------|
-| Python | `cognitive-modules` | `cogn` | `pip install cognitive-modules` |
-| Node.js | `cogn` or `cognitive-modules-cli` | `cog` | `npm install -g cogn` or `npx cogn` |
+| Python | `cognitive-modules` | `cog` | `pip install cognitive-modules` |
+| Node.js | `cognitive-modules-cli` | `cog` | `npm install -g cognitive-modules-cli` |
 
 Both versions share the same module format and v2.2 specification.
 
@@ -557,8 +468,6 @@ Both versions share the same module format and v2.2 specification.
 
 | Document | Description |
 |----------|-------------|
-| [SPEC-v2.5.md](SPEC-v2.5.md) | v2.5 full specification (Streaming, Multimodal) |
-| [SPEC-v2.5_zh.md](SPEC-v2.5_zh.md) | v2.5 规范中文版 |
 | [SPEC-v2.2.md](SPEC-v2.2.md) | v2.2 full specification (Control/Data separation, Tier, Overflow) |
 | [SPEC-v2.2_zh.md](SPEC-v2.2_zh.md) | v2.2 规范中文版 |
 | [SPEC.md](SPEC.md) | v0.1 specification (context philosophy) |

{cognitive_modules-0.6.1.dist-info → cognitive_modules-2.2.1.dist-info}/RECORD

@@ -4,15 +4,15 @@ cognitive/loader.py,sha256=NgFNcGXO56_1T1qxdvwWrpE37NoysTpuKhcQtchnros,15052
 cognitive/mcp_server.py,sha256=NUQT7IqdYB9tQ-1YYfG5MPJuq6A70FXlcV2x3lBnuvM,6852
 cognitive/migrate.py,sha256=FzdEwQvLWxmXy09fglV0YRxK4ozNeNT9UacfxGSJPZU,20156
 cognitive/registry.py,sha256=qLGyvUxSDP4frs46UlPa5jCcKubqiikWT3Y9JrBqfFc,18549
-cognitive/runner.py,sha256=KGIuB1pBxDX3l68HAvFUAKKhSJ3_2_IftmxpidULlts,46462
+cognitive/runner.py,sha256=87iC0eqj9U_CHJCubsYoP5OA-rXrfPibbffvDUkf00o,22114
 cognitive/server.py,sha256=cz8zGqhGrZgFY-HM0RSCjPCpB_Mfg1jsybeoo2ALvAc,9041
 cognitive/subagent.py,sha256=fb7LWwNF6YcJtC_T1dK0EvzqWMBnav-kiCIpvVohEBw,8142
 cognitive/templates.py,sha256=lKC197X9aQIA-npUvVCaplSwvhxjsH_KYVCQtrTZrL4,4712
 cognitive/validator.py,sha256=8B02JQQdNcwvH-mtbyP8bVTRQxUrO9Prt4gU0N53fdg,21843
 cognitive/providers/__init__.py,sha256=hqhVA1IEXpVtyCAteXhO5yD8a8ikQpVIPEKJVHLtRFY,7492
-cognitive_modules-0.6.1.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
-cognitive_modules-0.6.1.dist-info/METADATA,sha256=yMxvs8uHu_V8jjtKjr50ueUecx7q562GSBQGgZ-Ixes,18880
-cognitive_modules-0.6.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-cognitive_modules-0.6.1.dist-info/entry_points.txt,sha256=1yqKB-MjHrRoe8FcYm-TgZDqGEZxzBPsd0xC4pcfBNU,43
-cognitive_modules-0.6.1.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
-cognitive_modules-0.6.1.dist-info/RECORD,,
+cognitive_modules-2.2.1.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
+cognitive_modules-2.2.1.dist-info/METADATA,sha256=Cq2aLERDsebtIOkmGqibEEF8vzOPG2a7xRmzCDdqxe4,16975
+cognitive_modules-2.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cognitive_modules-2.2.1.dist-info/entry_points.txt,sha256=PKHlfrFmve5K2349ryipySKbOOsKxo_vIq1NNT-iBV0,42
+cognitive_modules-2.2.1.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
+cognitive_modules-2.2.1.dist-info/RECORD,,

cognitive_modules-2.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cog = cognitive.cli:app

cognitive_modules-0.6.1.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-cogn = cognitive.cli:app