ai-lib-python 0.6.0__tar.gz → 0.7.1__tar.gz

{ai_lib_python-0.6.0 → ai_lib_python-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-lib-python
-Version: 0.6.0
+Version: 0.7.1
 Summary: Official Python Runtime for AI-Protocol - The canonical Pythonic implementation for unified AI model interaction
 Project-URL: Homepage, https://github.com/hiddenpath/ai-lib-python
 Project-URL: Documentation, https://github.com/hiddenpath/ai-lib-python#readme
@@ -138,7 +138,7 @@ asyncio.run(main())
 
 ## 🔄 V2 Protocol Alignment
 
-Starting with v0.5.0, `ai-lib-python` aligns with the **AI-Protocol V2** specification:
+Starting with v0.5.0, `ai-lib-python` aligns with the **AI-Protocol V2** specification. V0.7.0 adds full V2 runtime support including V2 manifest parsing, provider drivers, MCP tool bridge, Computer Use abstraction, extended multimodal, and capability registry.
 
 ### Standard Error Codes (V2)
 
@@ -176,6 +176,20 @@ COMPLIANCE_DIR=../ai-protocol/tests/compliance pytest tests/compliance/ -v
 
 For details, see [CROSS_RUNTIME.md](https://github.com/hiddenpath/ai-protocol/blob/main/docs/CROSS_RUNTIME.md).
 
+### Testing with ai-protocol-mock
+
+For integration and MCP e2e tests without real API calls, use [ai-protocol-mock](https://github.com/hiddenpath/ai-protocol-mock):
+
+```bash
+# Start mock server (from ai-protocol-mock repo)
+docker-compose up -d
+
+# Run tests with mock
+MOCK_HTTP_URL=http://localhost:4010 MOCK_MCP_URL=http://localhost:4010/mcp pytest tests/ -v
+```
+
+Or in code: `AiClient.create("openai/gpt-4o", base_url="http://localhost:4010")`
+
 ## 📦 Installation
 
 ```bash
@@ -228,6 +242,8 @@ Provider manifests are resolved in a backward-compatible order:
 | `AI_LIB_RPS` | Rate limit (requests per second) | - |
 | `AI_LIB_BREAKER_FAILURE_THRESHOLD` | Circuit breaker failure threshold | 5 |
 | `AI_LIB_BREAKER_COOLDOWN_SECS` | Circuit breaker cooldown seconds | 30 |
+| `MOCK_HTTP_URL` | Mock server URL for testing (ai-protocol-mock) | - |
+| `MOCK_MCP_URL` | Mock MCP endpoint for testing | - |
 
 ### Provider API Keys
 
@@ -945,10 +961,15 @@ ai-lib-python/
 │   │   └── validator.py    # OutputValidator
 │   ├── utils/              # Utilities
 │   │   └── tool_call_assembler.py  # ToolCallAssembler
+│   ├── drivers/            # V2 provider drivers (OpenAI, Anthropic, Gemini)
+│   ├── mcp/                # MCP tool bridge
+│   ├── computer_use/       # Computer Use abstraction
+│   ├── multimodal/         # Extended multimodal support
+│   ├── registry/           # Capability registry
 │   └── errors/             # Error hierarchy
 ├── tests/
 │   ├── unit/               # Unit tests
-│   └── integration/        # Integration tests
+│   └── integration/        # Integration tests (incl. V2 compliance)
 ├── docs/                   # Documentation
 ├── examples/               # Example scripts
 └── pyproject.toml
@@ -956,7 +977,7 @@ ai-lib-python/
 
 ## 📖 Related Projects
 
-- [AI-Protocol](https://github.com/hiddenpath/ai-protocol) - Protocol specification (v1.5)
+- [AI-Protocol](https://github.com/hiddenpath/ai-protocol) - Protocol specification (v1.5 / V2)
 - [ai-lib-rust](https://github.com/hiddenpath/ai-lib-rust) - Rust runtime implementation
 
 ## 🤝 Contributing

{ai_lib_python-0.6.0 → ai_lib_python-0.7.1}/README.md

@@ -68,7 +68,7 @@ asyncio.run(main())
 
 ## 🔄 V2 Protocol Alignment
 
-Starting with v0.5.0, `ai-lib-python` aligns with the **AI-Protocol V2** specification:
+Starting with v0.5.0, `ai-lib-python` aligns with the **AI-Protocol V2** specification. V0.7.0 adds full V2 runtime support including V2 manifest parsing, provider drivers, MCP tool bridge, Computer Use abstraction, extended multimodal, and capability registry.
 
 ### Standard Error Codes (V2)
 
@@ -106,6 +106,20 @@ COMPLIANCE_DIR=../ai-protocol/tests/compliance pytest tests/compliance/ -v
 
 For details, see [CROSS_RUNTIME.md](https://github.com/hiddenpath/ai-protocol/blob/main/docs/CROSS_RUNTIME.md).
 
+### Testing with ai-protocol-mock
+
+For integration and MCP e2e tests without real API calls, use [ai-protocol-mock](https://github.com/hiddenpath/ai-protocol-mock):
+
+```bash
+# Start mock server (from ai-protocol-mock repo)
+docker-compose up -d
+
+# Run tests with mock
+MOCK_HTTP_URL=http://localhost:4010 MOCK_MCP_URL=http://localhost:4010/mcp pytest tests/ -v
+```
+
+Or in code: `AiClient.create("openai/gpt-4o", base_url="http://localhost:4010")`
+
 ## 📦 Installation
 
 ```bash
@@ -158,6 +172,8 @@ Provider manifests are resolved in a backward-compatible order:
 | `AI_LIB_RPS` | Rate limit (requests per second) | - |
 | `AI_LIB_BREAKER_FAILURE_THRESHOLD` | Circuit breaker failure threshold | 5 |
 | `AI_LIB_BREAKER_COOLDOWN_SECS` | Circuit breaker cooldown seconds | 30 |
+| `MOCK_HTTP_URL` | Mock server URL for testing (ai-protocol-mock) | - |
+| `MOCK_MCP_URL` | Mock MCP endpoint for testing | - |
 
 ### Provider API Keys
 
@@ -875,10 +891,15 @@ ai-lib-python/
 │   │   └── validator.py    # OutputValidator
 │   ├── utils/              # Utilities
 │   │   └── tool_call_assembler.py  # ToolCallAssembler
+│   ├── drivers/            # V2 provider drivers (OpenAI, Anthropic, Gemini)
+│   ├── mcp/                # MCP tool bridge
+│   ├── computer_use/       # Computer Use abstraction
+│   ├── multimodal/         # Extended multimodal support
+│   ├── registry/           # Capability registry
 │   └── errors/             # Error hierarchy
 ├── tests/
 │   ├── unit/               # Unit tests
-│   └── integration/        # Integration tests
+│   └── integration/        # Integration tests (incl. V2 compliance)
 ├── docs/                   # Documentation
 ├── examples/               # Example scripts
 └── pyproject.toml
@@ -886,7 +907,7 @@ ai-lib-python/
 
 ## 📖 Related Projects
 
-- [AI-Protocol](https://github.com/hiddenpath/ai-protocol) - Protocol specification (v1.5)
+- [AI-Protocol](https://github.com/hiddenpath/ai-protocol) - Protocol specification (v1.5 / V2)
 - [ai-lib-rust](https://github.com/hiddenpath/ai-lib-rust) - Rust runtime implementation
 
 ## 🤝 Contributing

{ai_lib_python-0.6.0 → ai_lib_python-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ai-lib-python"
-version = "0.6.0"
+version = "0.7.1"
 description = "Official Python Runtime for AI-Protocol - The canonical Pythonic implementation for unified AI model interaction"
 readme = "README.md"
 license = "MIT OR Apache-2.0"

{ai_lib_python-0.6.0 → ai_lib_python-0.7.1}/src/ai_lib_python/__init__.py

@@ -27,7 +27,7 @@ from ai_lib_python.types.message import (
 )
 from ai_lib_python.types.tool import ToolCall, ToolDefinition
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     # Client

ai_lib_python-0.7.1/src/ai_lib_python/computer_use/__init__.py

@@ -0,0 +1,228 @@
+"""Computer Use 抽象层 — 提供跨厂商的 GUI 自动化操作标准化和安全控制。
+
+Computer Use abstraction layer for AI-Protocol. Provides:
+- Normalized action types across providers (screen_based, tool_based)
+- Safety policy enforcement (confirmation, sandbox, logging, domain allowlist)
+- Provider-specific configuration extraction
+- Action validation before execution
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from urllib.parse import urlparse
+
+
+# ─── Normalized Action Types ────────────────────────────────────────────────
+
+
+class ActionType(str, Enum):
+    """Normalized computer use action types."""
+
+    SCREENSHOT = "screenshot"
+    MOUSE_CLICK = "mouse_click"
+    MOUSE_DOUBLE_CLICK = "mouse_double_click"
+    MOUSE_DRAG = "mouse_drag"
+    SCROLL = "scroll"
+    MOUSE_MOVE = "mouse_move"
+    KEYBOARD_TYPE = "keyboard_type"
+    KEYBOARD_SHORTCUT = "keyboard_shortcut"
+    BROWSER_NAVIGATE = "browser_navigate"
+    BROWSER_CLICK_ELEMENT = "browser_click_element"
+    BROWSER_FILL_FORM = "browser_fill_form"
+    ZOOM_REGION = "zoom_region"
+    FILE_READ = "file_read"
+    FILE_WRITE = "file_write"
+
+
+class MouseButton(str, Enum):
+    LEFT = "left"
+    RIGHT = "right"
+    MIDDLE = "middle"
+
+
+@dataclass
+class ComputerAction:
+    """A normalized computer use action — provider-agnostic."""
+
+    action_type: ActionType
+    params: dict[str, Any] = field(default_factory=dict)
+
+    # -- convenience factories --
+
+    @classmethod
+    def screenshot(cls, fmt: str = "png") -> ComputerAction:
+        return cls(ActionType.SCREENSHOT, {"format": fmt})
+
+    @classmethod
+    def mouse_click(
+        cls, x: float, y: float, button: MouseButton = MouseButton.LEFT
+    ) -> ComputerAction:
+        return cls(ActionType.MOUSE_CLICK, {"x": x, "y": y, "button": button.value})
+
+    @classmethod
+    def keyboard_type(cls, text: str) -> ComputerAction:
+        return cls(ActionType.KEYBOARD_TYPE, {"text": text})
+
+    @classmethod
+    def keyboard_shortcut(cls, keys: list[str]) -> ComputerAction:
+        return cls(ActionType.KEYBOARD_SHORTCUT, {"keys": keys})
+
+    @classmethod
+    def browser_navigate(cls, url: str) -> ComputerAction:
+        return cls(ActionType.BROWSER_NAVIGATE, {"url": url})
+
+    @classmethod
+    def file_read(cls, path: str) -> ComputerAction:
+        return cls(ActionType.FILE_READ, {"path": path})
+
+    @classmethod
+    def file_write(cls, path: str, content: str) -> ComputerAction:
+        return cls(ActionType.FILE_WRITE, {"path": path, "content": content})
+
+
+class ImplementationStyle(str, Enum):
+    """Provider implementation approach."""
+
+    SCREEN_BASED = "screen_based"
+    TOOL_BASED = "tool_based"
+    HYBRID = "hybrid"
+
+
+class SandboxMode(str, Enum):
+    REQUIRED = "required"
+    RECOMMENDED = "recommended"
+    OPTIONAL = "optional"
+
+
+# ─── Safety Policy ──────────────────────────────────────────────────────────
+
+
+class SafetyViolation(Exception):
+    """Raised when a computer use action violates the safety policy."""
+
+
+@dataclass
+class SafetyPolicy:
+    """Safety policy for computer use actions.
+
+    Loaded from the manifest's ``computer_use.safety`` configuration.
+    All validations are enforced *before* the action is dispatched.
+    """
+
+    confirmation_required: bool = True
+    sandbox_mode: SandboxMode = SandboxMode.RECOMMENDED
+    action_logging: bool = True
+    domain_allowlist: set[str] = field(default_factory=set)
+    sensitive_data_protection: bool = True
+    max_actions_per_turn: int = 0
+    action_timeout_ms: int = 30_000
+
+    @classmethod
+    def from_config(cls, safety_dict: dict[str, Any] | None) -> SafetyPolicy:
+        """Build a safety policy from a manifest's ``computer_use.safety`` dict."""
+        if not safety_dict:
+            return cls()
+        return cls(
+            confirmation_required=safety_dict.get("confirmation_required", True),
+            sandbox_mode=SandboxMode(safety_dict.get("sandbox_mode", "recommended")),
+            action_logging=safety_dict.get("action_logging", True),
+            domain_allowlist=set(safety_dict.get("domain_allowlist_entries", [])),
+            sensitive_data_protection=safety_dict.get("sensitive_data_protection", True),
+            max_actions_per_turn=safety_dict.get("max_actions_per_turn", 0),
+            action_timeout_ms=safety_dict.get("action_timeout_ms", 30_000),
+        )
+
+    def validate_action(
+        self,
+        action: ComputerAction,
+        actions_this_turn: int = 0,
+    ) -> None:
+        """Validate an action against this policy. Raises :class:`SafetyViolation`."""
+        if self.max_actions_per_turn > 0 and actions_this_turn >= self.max_actions_per_turn:
+            raise SafetyViolation(
+                f"Max actions per turn exceeded: limit={self.max_actions_per_turn}, "
+                f"attempted={actions_this_turn + 1}"
+            )
+
+        if action.action_type == ActionType.BROWSER_NAVIGATE and self.domain_allowlist:
+            url = action.params.get("url", "")
+            domain = _extract_domain(url)
+            if domain not in self.domain_allowlist:
+                raise SafetyViolation(
+                    f"Domain '{domain}' is not in the allowlist: {sorted(self.domain_allowlist)}"
+                )
+
+        if self.sensitive_data_protection and action.action_type in (
+            ActionType.FILE_READ,
+            ActionType.FILE_WRITE,
+        ):
+            path = action.params.get("path", "")
+            if _is_sensitive_path(path):
+                raise SafetyViolation(f"Access to sensitive path '{path}' is blocked")
+
+
+# ─── Provider Configuration ─────────────────────────────────────────────────
+
+
+@dataclass
+class CuProviderConfig:
+    """Provider-specific computer use configuration."""
+
+    tool_type: str = "computer_use"
+    beta_header: str | None = None
+    implementation: ImplementationStyle = ImplementationStyle.SCREEN_BASED
+    model_requirement: str | None = None
+
+
+def extract_provider_config(cu_config: dict[str, Any] | None) -> CuProviderConfig | None:
+    """Extract provider-specific CU configuration from a manifest section."""
+    if not cu_config or not cu_config.get("supported"):
+        return None
+
+    impl_str = cu_config.get("implementation", "screen_based")
+    implementation = ImplementationStyle(impl_str)
+
+    mapping = cu_config.get("provider_mapping", {})
+    return CuProviderConfig(
+        tool_type=mapping.get("tool_type", "computer_use"),
+        beta_header=mapping.get("beta_header"),
+        implementation=implementation,
+        model_requirement=mapping.get("model_requirement"),
+    )
+
+
+# ─── Helpers ────────────────────────────────────────────────────────────────
+
+_SENSITIVE_PATTERNS = (
+    ".ssh", ".gnupg", ".aws", "credentials", "secrets",
+    ".env", "password", "token", ".kube/config",
+)
+
+
+def _extract_domain(url: str) -> str:
+    try:
+        parsed = urlparse(url)
+        return parsed.hostname or ""
+    except Exception:
+        return url.split("//")[-1].split("/")[0].split(":")[0]
+
+
+def _is_sensitive_path(path: str) -> bool:
+    lower = path.lower()
+    return any(p in lower for p in _SENSITIVE_PATTERNS)
+
+
+__all__ = [
+    "ActionType",
+    "ComputerAction",
+    "CuProviderConfig",
+    "ImplementationStyle",
+    "MouseButton",
+    "SafetyPolicy",
+    "SafetyViolation",
+    "SandboxMode",
+    "extract_provider_config",
+]

ai_lib_python-0.7.1/src/ai_lib_python/drivers/__init__.py

@@ -0,0 +1,140 @@
+"""Provider 驱动抽象层 — 通过 ABC 实现多厂商 API 适配的动态分发。
+
+Provider driver abstraction layer implementing the ProviderContract specification.
+Uses abstract base class + factory for runtime polymorphism, enabling the same
+client code to work with OpenAI, Anthropic, Gemini, and any compatible provider.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from ai_lib_python.protocol.v2.capabilities import Capability
+from ai_lib_python.protocol.v2.manifest import ApiStyle
+from ai_lib_python.types.events import StreamingEvent
+from ai_lib_python.types.message import Message
+
+
+@dataclass
+class DriverRequest:
+    """Unified HTTP request representation for provider communication."""
+
+    url: str = ""
+    method: str = "POST"
+    headers: dict[str, str] = field(default_factory=dict)
+    body: dict[str, Any] = field(default_factory=dict)
+    stream: bool = False
+
+
+@dataclass
+class DriverResponse:
+    """Unified chat response from provider."""
+
+    content: str | None = None
+    finish_reason: str | None = None
+    usage: UsageInfo | None = None
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UsageInfo:
+    """Token usage information."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class ProviderDriver(ABC):
+    """Core abstract class for provider-specific API adaptation.
+
+    Each provider API style (OpenAI, Anthropic, Gemini) has a concrete
+    implementation. The runtime selects the correct driver based on the
+    manifest's ``api_style`` or ``provider_contract``.
+    """
+
+    @property
+    @abstractmethod
+    def provider_id(self) -> str:
+        """Unique provider identifier (matches manifest ``id``)."""
+
+    @property
+    @abstractmethod
+    def api_style(self) -> ApiStyle:
+        """API style this driver implements."""
+
+    @abstractmethod
+    def build_request(
+        self,
+        messages: list[Message],
+        model: str,
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        stream: bool = False,
+        extra: dict[str, Any] | None = None,
+    ) -> DriverRequest:
+        """Build a provider-specific HTTP request from unified parameters."""
+
+    @abstractmethod
+    def parse_response(self, body: dict[str, Any]) -> DriverResponse:
+        """Parse a non-streaming response into unified format."""
+
+    @abstractmethod
+    def parse_stream_event(self, data: str) -> StreamingEvent | None:
+        """Parse a single streaming event from raw SSE/NDJSON data."""
+
+    @abstractmethod
+    def supported_capabilities(self) -> list[Capability]:
+        """Get the list of capabilities this driver supports."""
+
+    @abstractmethod
+    def is_stream_done(self, data: str) -> bool:
+        """Check if the done signal has been received in streaming."""
+
+
+# ---------------------------------------------------------------------------
+# Concrete drivers (imported lazily to avoid circular deps)
+# ---------------------------------------------------------------------------
+
+from ai_lib_python.drivers.anthropic import AnthropicDriver  # noqa: E402
+from ai_lib_python.drivers.gemini import GeminiDriver  # noqa: E402
+from ai_lib_python.drivers.openai import OpenAiDriver  # noqa: E402
+
+
+def create_driver(
+    api_style: ApiStyle,
+    provider_id: str,
+    capabilities: list[Capability] | None = None,
+) -> ProviderDriver:
+    """Factory: create the appropriate driver from an API style.
+
+    ``Custom`` falls back to OpenAI-compatible, which covers most
+    providers that follow the OpenAI chat completions format (DeepSeek,
+    Moonshot, Zhipu, etc.).
+    """
+    caps = capabilities or []
+    match api_style:
+        case ApiStyle.OPENAI_COMPATIBLE | ApiStyle.CUSTOM:
+            return OpenAiDriver(provider_id=provider_id, capabilities=caps)
+        case ApiStyle.ANTHROPIC_MESSAGES:
+            return AnthropicDriver(provider_id=provider_id, capabilities=caps)
+        case ApiStyle.GEMINI_GENERATE:
+            return GeminiDriver(provider_id=provider_id, capabilities=caps)
+        case _:
+            return OpenAiDriver(provider_id=provider_id, capabilities=caps)
+
+
+__all__ = [
+    "AnthropicDriver",
+    "DriverRequest",
+    "DriverResponse",
+    "GeminiDriver",
+    "OpenAiDriver",
+    "ProviderDriver",
+    "UsageInfo",
+    "create_driver",
+]