feat: initial release of CUP Python SDK

Python SDK for the Computer Use Protocol — tree capture, action
execution, semantic search, and MCP server for AI agent integration.

Extracted from computeruseprotocol/computer-use-protocol.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: k4cper-g

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+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"
+
+      - 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"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v

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

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/computer-use-protocol](https://github.com/computeruseprotocol/computer-use-protocol).
+
+### 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 Windows and Web platforms (macOS and Linux planned)
+- **MCP server** (`cup-mcp`) with 7 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 `capture()`, `execute()`, `press_keys()`, `find_elements()`, `batch_execute()`, 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

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

CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# 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 [computer-use-protocol](https://github.com/computeruseprotocol/computer-use-protocol).
+
+## 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
+- **macOS / Linux action execution** — currently tree capture only
+- **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).

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.