computeruseprotocol 0.1.0__py3-none-any.whl

computeruseprotocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: computeruseprotocol
+Version: 0.1.0
+Summary: Python SDK for the Computer Use Protocol — universal cross-platform UI accessibility
+Project-URL: Homepage, https://computeruseprotocol.com
+Project-URL: Repository, https://github.com/computeruseprotocol/python-sdk
+Project-URL: Specification, https://github.com/computeruseprotocol/computeruseprotocol
+Project-URL: Documentation, https://computeruseprotocol.com
+Author-email: CUP Contributors <cup@computeruseprotocol.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,ai-agents,aria,computer-use,ui-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: comtypes>=1.2; sys_platform == 'win32'
+Requires-Dist: pyobjc-framework-applicationservices>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-cocoa>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.20; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.6; extra == 'mcp'
+Requires-Dist: mss>=6.0; extra == 'mcp'
+Provides-Extra: screenshot
+Requires-Dist: mss>=6.0; extra == 'screenshot'
+Provides-Extra: web
+Requires-Dist: websocket-client>=1.6; extra == 'web'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://computeruseprotocol.com">
+    <img src="assets/banner.png" alt="Computer Use Protocol">
+  </a>
+</p>
+
+<p align="center">
+  <b>Python SDK for the Computer Use Protocol</b>
+</p>
+
+<br>
+
+<p align="center">
+  <a href="https://pypi.org/project/computeruseprotocol"><img src="https://img.shields.io/pypi/v/computeruseprotocol?style=for-the-badge&color=FF6F61&labelColor=000000" alt="PyPI"></a>
+  <a href="https://github.com/computeruseprotocol/python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-0cc0df?style=for-the-badge&labelColor=000000" alt="MIT License"></a>
+  <a href="https://github.com/computeruseprotocol/computeruseprotocol"><img src="https://img.shields.io/badge/Spec-computer--use--protocol-7ed957?style=for-the-badge&labelColor=000000" alt="Spec"></a>
+</p>
+
+The official Python SDK for the [Computer Use Protocol (CUP)](https://github.com/computeruseprotocol/computeruseprotocol) — a universal protocol for AI agents to perceive and interact with any desktop UI. This package provides tree capture, action execution, semantic search, and an MCP server for AI agent integration.
+
+## Installation
+
+```bash
+pip install computeruseprotocol
+
+# Linux additionally requires system packages
+sudo apt install python3-gi gir1.2-atspi-2.0
+
+# Web adapter (Chrome DevTools Protocol, works on any OS)
+pip install computeruseprotocol[web]
+
+# Screenshot support (mss; not needed on macOS)
+pip install computeruseprotocol[screenshot]
+
+# MCP server for AI agent integration
+pip install computeruseprotocol[mcp]
+```
+
+## Quick start
+
+```python
+import cup
+
+# Snapshot the foreground window — optimized for LLM context windows
+screen = cup.snapshot()
+print(screen)
+
+# All windows
+screen = cup.snapshot("full")
+
+# Structured CUP envelope (dict) instead of compact text
+envelope = cup.snapshot_raw()
+```
+
+Output:
+
+```
+# CUP 0.1.0 | windows | 2560x1440
+# app: Spotify
+# 63 nodes (280 before pruning)
+
+[e0] win "Spotify" 120,40 1680x1020
+  [e1] doc "Spotify" 120,40 1680x1020
+    [e2] btn "Back" 132,52 32x32 [clk]
+    [e3] btn "Forward" 170,52 32x32 {dis} [clk]
+    [e7] nav "Main" 120,88 240x972
+      [e8] lnk "Home" 132,100 216x40 {sel} [clk]
+      [e9] lnk "Search" 132,148 216x40 [clk]
+```
+
+## CLI
+
+```bash
+# Print the foreground window tree (default)
+python -m cup
+
+# Filter by app name
+python -m cup --scope full --app Discord
+
+# Save JSON envelope to file
+python -m cup --json-out tree.json
+
+# Capture from Chrome via CDP
+python -m cup --platform web --cdp-port 9222
+
+# Include diagnostics (timing, role distribution, sizes)
+python -m cup --verbose
+```
+
+## Platform support
+
+| Platform | Adapter | Tree Capture | Actions |
+|----------|---------|-------------|---------|
+| Windows | UIA COM (comtypes) | Stable | Stable |
+| macOS | AXUIElement (pyobjc) | Stable | Stable |
+| Linux | AT-SPI2 (PyGObject) | Stable | Stable |
+| Web | Chrome DevTools Protocol | Stable | Stable |
+| Android | | Planned | Planned |
+| iOS | | Planned | Planned |
+
+CUP auto-detects your platform. Platform-specific dependencies (comtypes on Windows, pyobjc on macOS) are installed automatically.
+
+## Architecture
+
+```
+cup/
+├── __init__.py                 # Public API: snapshot, action, find, ...
+├── __main__.py                 # CLI entry point
+├── _base.py                    # Abstract PlatformAdapter interface
+├── _router.py                  # Platform detection & adapter dispatch
+├── format.py                   # Envelope builder, compact serializer, tree pruning
+├── search.py                   # Semantic element search with fuzzy matching
+├── actions/                    # Action execution layer
+│   ├── executor.py             # ActionExecutor orchestrator
+│   ├── _handler.py             # Abstract ActionHandler interface
+│   ├── _keys.py                # Key name mapping utilities
+│   ├── _windows.py             # Windows UIA actions
+│   ├── _web.py                 # Chrome CDP actions
+│   ├── _macos.py               # macOS actions (Quartz CGEvents + AX)
+│   └── _linux.py               # Linux actions (XTest + AT-SPI2)
+├── platforms/                  # Platform-specific tree capture
+│   ├── windows.py              # Windows UIA adapter
+│   ├── macos.py                # macOS AXUIElement adapter
+│   ├── linux.py                # Linux AT-SPI2 adapter
+│   └── web.py                  # Chrome CDP adapter
+└── mcp/                        # MCP server integration
+    ├── __main__.py             # python -m cup.mcp entry point
+    └── server.py               # MCP protocol server
+```
+
+Adding a new platform means implementing `PlatformAdapter` — see [cup/_base.py](cup/_base.py) for the interface.
+
+## MCP Server
+
+CUP ships an MCP server for integration with AI agents (Claude, Copilot, etc.).
+
+```bash
+# Run directly
+cup-mcp
+
+# Or via Python
+python -m cup.mcp
+```
+
+Add to your MCP client config (e.g., `.mcp.json` for Claude Code):
+
+```json
+{
+    "mcpServers": {
+        "cup": {
+            "command": "cup-mcp",
+            "args": []
+        }
+    }
+}
+```
+
+**Tools:** `snapshot`, `snapshot_app`, `overview`, `snapshot_desktop`, `find`, `action`, `open_app`, `screenshot`
+
+## Contributing
+
+CUP is in early development (v0.1.0). Contributions welcome — especially:
+
+- Android adapter (`cup/platforms/android.py`)
+- iOS adapter (`cup/platforms/ios.py`)
+- Tests — especially cross-platform integration tests
+- Documentation and examples
+
+For protocol or schema changes, please contribute to [computeruseprotocol](https://github.com/computeruseprotocol/computeruseprotocol).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+
+## Documentation
+
+- **[API Reference](docs/api-reference.md)** — Session API, actions, envelope format, MCP server
+- **[Protocol Specification](https://github.com/computeruseprotocol/computeruseprotocol)** — Schema, roles, states, actions, compact format
+
+## License
+
+[MIT](LICENSE)

computeruseprotocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+cup/__init__.py,sha256=Su-DHp4rCCBImwa9f2yWO54D0z_dOKlkYOXkzjOgnfM,18744
+cup/__main__.py,sha256=RdBUOjYb2CwzPAMOBbh3u0ycjDTl6y9DdXEkBTKBN00,7823
+cup/_base.py,sha256=c7rdQ7S9sCG82N2-jaRk_VIYulFynRMV_YvwnxHiHB4,3919
+cup/_router.py,sha256=EAIIDIM93gltf1vHDC9fQ7D6oazRV1rIYUUXdzvfPCQ,1786
+cup/format.py,sha256=poBK6MMnqD6NpoedZX3PqqDi050PysCLSSHoU85db28,22058
+cup/search.py,sha256=Nvshkxkcbkodv21liULmQ5BWjq6WP3rsMnTM01AzCxU,17737
+cup/actions/__init__.py,sha256=-BD-tzvyQSeBLAtdq2blz-VHLAL9hXzgzi9TZML1fZ0,238
+cup/actions/_handler.py,sha256=roNDyZ6PZpomC-hRjh-RDHKKPNYYY8TDIn_hz1IwGeo,1744
+cup/actions/_keys.py,sha256=huWYIsZ0nTY4mhg6VicXZqqmT6OwW6P0T74R1JibtiQ,1467
+cup/actions/_linux.py,sha256=3nUBP9fwHVtY4InhHbSyWoDNrXi4-01YMZGo7JoErIs,34345
+cup/actions/_macos.py,sha256=9i9681aQsC3KMUS8Yu02CK2e3A6PMH52ZKnGxCUW3zI,35605
+cup/actions/_web.py,sha256=p-9ggmXdUlcasMUlmZAc0bXDZStTtQWFkR719UUfNng,18127
+cup/actions/_windows.py,sha256=1YWoWVKG-OZmHJk__X5bl8bMEtoGy_oxSD3vUDSdOCU,33119
+cup/actions/executor.py,sha256=dE70ADgGSOjxWSuviJ-TVbwpNTGHOj1AfZM4Zox1MlQ,5072
+cup/mcp/__init__.py,sha256=yypL_prk481sh0iwLQyknDZDtxidDMiz4YzY5kQTDkg,81
+cup/mcp/__main__.py,sha256=Kpv5pKBPIGGvnL1JCfMewrJlRWFM-K3NEAEAwv1GpJo,165
+cup/mcp/server.py,sha256=HTzvAc4oCjq2lX-SnNKc8teEaKWzFDKBOk9pMNTovGU,14184
+cup/platforms/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cup/platforms/linux.py,sha256=Hn2daC1ElO52Ry1utiE3FLQfvhG2L-rZys7lskZOnPE,34483
+cup/platforms/macos.py,sha256=uWVeoOdE52AtSPXTFRAR8dG9gD3f_zU-3kVHlb96Cz4,33959
+cup/platforms/web.py,sha256=B5MTew-c0Mpm6ADIJT0diCX-WuXWvpqL8FM_qMQedqg,28459
+cup/platforms/windows.py,sha256=5dnkDkrTPzP9kTbFh4lI-Xc_ffaaNbiUrCynYcai-TU,30584
+computeruseprotocol-0.1.0.dist-info/METADATA,sha256=21bOFa4m6eVbGDlph0GQd9KQFDYopBVFCGm1e2eLYJs,8139
+computeruseprotocol-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+computeruseprotocol-0.1.0.dist-info/entry_points.txt,sha256=1EqVMxnleaiwEqZOXDOK3aTlE7NLryDoZynVL3hs4q8,74
+computeruseprotocol-0.1.0.dist-info/licenses/LICENSE,sha256=IBBlg1YoktpxlPHFtZflf91aHz9YLc92KbEyK3pTLeY,1073
+computeruseprotocol-0.1.0.dist-info/RECORD,,

computeruseprotocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

computeruseprotocol-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cup = cup.__main__:main
+cup-mcp = cup.mcp.__main__:main

computeruseprotocol-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CUP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.