computeruseprotocol 0.1.0__tar.gz

computeruseprotocol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check cup/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check cup/ tests/
+
+      - name: Mypy
+        run: mypy cup/ --ignore-missing-imports
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.14"
+            experimental: true
+    continue-on-error: ${{ matrix.experimental || false }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          allow-prereleases: true
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,web,screenshot]"
+
+      - name: Run tests with coverage
+        run: pytest -v --cov=cup --cov-report=xml --cov-report=term-missing
+
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify wheel installs cleanly
+        run: |
+          pip install dist/*.whl
+          python -c "import cup; print('cup imported successfully')"
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,web,screenshot]"
+
+      - name: Audit dependencies
+        run: pip install pip-audit && pip-audit

computeruseprotocol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

computeruseprotocol-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Environment
+.env
+.mcp.json
+.claude/
+
+# Runs / output data
+runs/
+benchmark/
+
+# Testing
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/

computeruseprotocol-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-02-23
+
+Initial release. Extracted from [computeruseprotocol/computeruseprotocol](https://github.com/computeruseprotocol/computeruseprotocol).
+
+### Added
+- **Platform adapters** for tree capture:
+  - Windows (UIA COM via comtypes)
+  - macOS (AXUIElement via pyobjc)
+  - Linux (AT-SPI2 via PyGObject)
+  - Web (Chrome DevTools Protocol)
+- **Action execution** on all four platforms (Windows, macOS, Linux, Web)
+- **MCP server** (`cup-mcp`) with 8 tools for AI agent integration
+- **Semantic search engine** with fuzzy matching, role synonyms, and relevance ranking
+- **Viewport-aware pruning** that clips offscreen nodes using nested scrollable container intersection
+- **Session API** with `snapshot()`, `action()`, `press()`, `find()`, `batch()`, and `screenshot()`
+- **CLI** (`python -m cup`) for tree capture, JSON export, and compact output
+- **CI** with GitHub Actions running tests on Windows, macOS, and Linux
+
+[0.1.0]: https://github.com/computeruseprotocol/python-sdk/releases/tag/v0.1.0

computeruseprotocol-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,58 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at **cup@computeruseprotocol.com**.
+
+All complaints will be reviewed and investigated promptly and fairly. All
+community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

computeruseprotocol-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to the CUP Python SDK
+
+Thanks for your interest in the Computer Use Protocol! CUP is in early development (v0.1.0) and contributions are welcome.
+
+> For changes to the protocol schema, compact format spec, or role mappings, please contribute to [computeruseprotocol](https://github.com/computeruseprotocol/computeruseprotocol).
+
+## Getting started
+
+1. Fork the repository and clone your fork
+2. Create a virtual environment and install dev dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+3. Run the test suite to verify your setup:
+
+```bash
+pytest -v
+```
+
+## Making changes
+
+1. Create a branch from `main`:
+
+```bash
+git checkout -b my-feature
+```
+
+2. Make your changes. Follow existing code style — type hints, docstrings on public APIs, 4-space indentation.
+
+3. Add or update tests for any changed behavior. Tests live in `tests/`.
+
+4. Run the full suite and ensure it passes:
+
+```bash
+pytest -v
+```
+
+5. Run linting and type checks:
+
+```bash
+ruff check cup/ tests/
+mypy cup/
+```
+
+6. Open a pull request against `main`. Describe what you changed and why.
+
+## What we're looking for
+
+High-impact areas where contributions are especially useful:
+
+- **Android adapter** (`cup/platforms/android.py`) — ADB + AccessibilityNodeInfo
+- **iOS adapter** (`cup/platforms/ios.py`) — XCUITest accessibility
+- **Tests** — especially cross-platform integration tests
+- **Documentation** — tutorials, examples, API reference improvements
+
+## Pull request guidelines
+
+- Keep PRs focused. One feature or fix per PR.
+- Include tests for new functionality.
+- Update documentation if you change public APIs.
+- Ensure CI passes before requesting review.
+
+## Reporting bugs
+
+Open an issue with:
+- Platform and Python version
+- Minimal reproduction steps
+- Expected vs. actual behavior
+- Full traceback if applicable
+
+## Code style
+
+- Python 3.10+ with `from __future__ import annotations`
+- Type hints on all public function signatures
+- Docstrings on public classes and functions (Google style)
+- No unnecessary dependencies — platform deps are conditional
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

computeruseprotocol-0.1.0/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.

computeruseprotocol-0.1.0/PKG-INFO

@@ -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)