From 944ab65e7905eb8de215066b4af7221a74aaef23 Mon Sep 17 00:00:00 2001 From: James Murdza Date: Fri, 5 Sep 2025 02:54:28 -0400 Subject: [PATCH] Restore Developer-Guide.mdx deleted in 2d7b5d7 --- docs/content/docs/v1/Developer-Guide.mdx | 290 +++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 docs/content/docs/v1/Developer-Guide.mdx diff --git a/docs/content/docs/v1/Developer-Guide.mdx b/docs/content/docs/v1/Developer-Guide.mdx new file mode 100644 index 00000000..304ecb09 --- /dev/null +++ b/docs/content/docs/v1/Developer-Guide.mdx @@ -0,0 +1,290 @@ +--- +title: Developer Guide +description: Cua Monorepo Developer Guide +--- +# Getting Started + +## Project Structure + +The project is organized as a monorepo with these main packages: + +- `libs/core/` - Base package with telemetry support +- `libs/computer/` - Computer-use interface (CUI) library +- `libs/agent/` - AI agent library with multi-provider support +- `libs/som/` - Set-of-Mark parser +- `libs/computer-server/` - Server component for VM +- `libs/lume/` - Lume CLI +- `libs/pylume/` - Python bindings for Lume + +Each package has its own virtual environment and dependencies, managed through PDM. + +## Local Development Setup + +1. Install Lume CLI: + + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" + ``` + +2. Clone the repository: + + ```bash + git clone https://github.com/trycua/cua.git + cd cua + ``` + +3. Create a `.env.local` file in the root directory with your API keys: + + ```bash + # Required for Anthropic provider + ANTHROPIC_API_KEY=your_anthropic_key_here + + # Required for OpenAI provider + OPENAI_API_KEY=your_openai_key_here + ``` + +4. Open the workspace in VSCode or Cursor: + + ```bash + # For Cua Python development + code .vscode/py.code-workspace + + # For Lume (Swift) development + code .vscode/lume.code-workspace + ``` + +Using the workspace file is strongly recommended as it: + +- Sets up correct Python environments for each package +- Configures proper import paths +- Enables debugging configurations +- Maintains consistent settings across packages + +## Lume Development + +Refer to the [Lume README](../libs/lume/docs/Development.md) for instructions on how to develop the Lume CLI. + +## Python Development + +There are two ways to install Lume: + +### Run the build script + +Run the build script to set up all packages: + +```bash +./scripts/build.sh +``` + +The build script creates a shared virtual environment for all packages. The workspace configuration automatically handles import paths with the correct Python path settings. + +This will: + +- Create a virtual environment for the project +- Install all packages in development mode +- Set up the correct Python path +- Install development tools + +### Install with PDM + +If PDM is not already installed, you can follow the installation instructions [here](https://pdm-project.org/en/latest/#installation). + +To install with PDM, simply run: + +```console +pdm install -G:all +``` + +This installs all the dependencies for development, testing, and building the docs. If you'd only like development dependencies, you can run: + +```console +pdm install -d +``` + +## Running Examples + +The Python workspace includes launch configurations for all packages: + +- "Run Computer Examples" - Runs computer examples +- "Run Computer API Server" - Runs the computer-server +- "Run Agent Examples" - Runs agent examples +- "SOM" configurations - Various settings for running SOM + +To run examples from VSCode / Cursor: + +1. Press F5 or use the Run/Debug view +2. Select the desired configuration + +The workspace also includes compound launch configurations: + +- "Run Computer Examples + Server" - Runs both the Computer Examples and Server simultaneously + +## Docker Development Environment + +As an alternative to installing directly on your host machine, you can use Docker for development. This approach has several advantages: + +### Prerequisites + +- Docker installed on your machine +- Lume server running on your host (port 7777): `lume serve` + +### Setup and Usage + +1. Build the development Docker image: + + ```bash + ./scripts/run-docker-dev.sh build + ``` + +2. Run an example in the container: + + ```bash + ./scripts/run-docker-dev.sh run computer_examples.py + ``` + +3. Get an interactive shell in the container: + + ```bash + ./scripts/run-docker-dev.sh run --interactive + ``` + +4. Stop any running containers: + + ```bash + ./scripts/run-docker-dev.sh stop + ``` + +### How it Works + +The Docker development environment: + +- Installs all required Python dependencies in the container +- Mounts your source code from the host at runtime +- Automatically configures the connection to use host.docker.internal:7777 for accessing the Lume server on your host machine +- Preserves your code changes without requiring rebuilds (source code is mounted as a volume) + +> **Note**: The Docker container doesn't include the macOS-specific Lume executable. Instead, it connects to the Lume server running on your host machine via host.docker.internal:7777. Make sure to start the Lume server on your host before running examples in the container. + +## Cleanup and Reset + +If you need to clean up the environment (non-docker) and start fresh: + +```bash +./scripts/cleanup.sh +``` + +This will: + +- Remove all virtual environments +- Clean Python cache files and directories +- Remove build artifacts +- Clean PDM-related files +- Reset environment configurations + +## Code Formatting Standards + +The cua project follows strict code formatting standards to ensure consistency across all packages. + +### Python Code Formatting + +#### Tools + +The project uses the following tools for code formatting and linting: + +- **[Black](https://black.readthedocs.io/)**: Code formatter +- **[Ruff](https://beta.ruff.rs/docs/)**: Fast linter and formatter +- **[MyPy](https://mypy.readthedocs.io/)**: Static type checker + +These tools are automatically installed when you set up the development environment using the `./scripts/build.sh` script. + +#### Configuration + +The formatting configuration is defined in the root `pyproject.toml` file: + +```toml +[tool.black] +line-length = 100 +target-version = ["py311"] + +[tool.ruff] +line-length = 100 +target-version = "py311" +select = ["E", "F", "B", "I"] +fix = true + +[tool.ruff.format] +docstring-code-format = true + +[tool.mypy] +strict = true +python_version = "3.11" +ignore_missing_imports = true +disallow_untyped_defs = true +check_untyped_defs = true +warn_return_any = true +show_error_codes = true +warn_unused_ignores = false +``` + +#### Key Formatting Rules + +- **Line Length**: Maximum of 100 characters +- **Python Version**: Code should be compatible with Python 3.11+ +- **Imports**: Automatically sorted (using Ruff's "I" rule) +- **Type Hints**: Required for all function definitions (strict mypy mode) + +#### IDE Integration + +The repository includes VSCode workspace configurations that enable automatic formatting. When you open the workspace files (as recommended in the setup instructions), the correct formatting settings are automatically applied. + +Python-specific settings in the workspace files: + +```json +"[python]": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "ms-python.black-formatter", + "editor.codeActionsOnSave": { + "source.organizeImports": "explicit" + } +} +``` + +Recommended VS Code extensions: + +- Black Formatter (ms-python.black-formatter) +- Ruff (charliermarsh.ruff) +- Pylance (ms-python.vscode-pylance) + +#### Manual Formatting + +To manually format code: + +```bash +# Format all Python files using Black +pdm run black . + +# Run Ruff linter with auto-fix +pdm run ruff check --fix . + +# Run type checking with MyPy +pdm run mypy . +``` + +#### Pre-commit Validation + +Before submitting a pull request, ensure your code passes all formatting checks: + +```bash +# Run all checks +pdm run black --check . +pdm run ruff check . +pdm run mypy . +``` + +### Swift Code (Lume) + +For Swift code in the `libs/lume` directory: + +- Follow the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/) +- Use SwiftFormat for consistent formatting +- Code will be automatically formatted on save when using the lume workspace