somew1nd
206a9ce921
ARTEMIS is an autonomous multimodal Android agent and mobile UI automation platform engineered for physical devices and emulators. It combines state-of-the-art multimodal Vision-Language Models (VLMs) with hierarchical closed-loop planning, resilient self-healing, and deep Android subsystem integration. Key Features & Architectural Highlights: - Dual-Engine Orchestration: * Pro Engine: Multi-agent closed-loop (Planner -> Operator -> Validator/Failure Analyzer -> Summarizer) powered by LangGraph. * Flash Engine: Ultra-fast reactive loop for deterministic, low-latency UI execution (<35 steps). - Multimodal Perception & Grounding: * Hybrid visual screenshot grounding, real-time OCR extraction, and XML accessibility hierarchy parsing. * Dynamic-First, Coordinate-Fallback locating strategy for maximum resilience against UI drift. - Autonomous Self-Healing & Diagnostics: * Failure analyzer and safety net for popup dismissal, crash recovery, and auto-retry. * Diagnostic sub-agents for log analysis, video recording inspection, and object detection. - Unified CLI & Python SDK: * Rich CLI with commands: init, doctor, run, trace, batch, bench, server, and mcp. * Fluent Python SDK with Pydantic structured output models and package locking. - Multi-Provider LLM Architecture: * Support for Google Gemini, OpenAI, Anthropic Claude, Vertex AI, OpenRouter, xAI Grok, and local endpoints (Ollama/vLLM). * Centralized configuration in config/artemis.jsonc. - Native MCP & Observability: * Model Context Protocol (MCP) server endpoints for AI IDEs. * Full trace recording with before/after screenshots, action overlays, and execution replays. Change-Id: I430b93ee2b76b54cc5a3c6eeccd15d2cf29830a1
104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# How to Contribute
|
|
|
|
We'd love to accept your patches and contributions to ARTEMIS! There are just a few small guidelines you need to follow.
|
|
|
|
---
|
|
|
|
## Contributor License Agreement (CLA)
|
|
|
|
Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.
|
|
|
|
- Head over to <https://cla.developers.google.com/> to check your current agreements on file or to sign a new one.
|
|
- If you are an individual contributing original source code, you must sign the **Individual CLA**.
|
|
- If you are contributing on behalf of a company or organization, a **Corporate CLA** must be executed by your employer.
|
|
- You generally only need to submit a CLA once, so if you have already submitted one for another Google project, you do not need to sign it again.
|
|
|
|
---
|
|
|
|
## Community Guidelines
|
|
|
|
This project adheres to [Google's Open Source Community Guidelines](https://opensource.google/conduct/). By participating, all contributors and maintainers are expected to uphold these principles and maintain a welcoming, inclusive, and professional environment.
|
|
|
|
---
|
|
|
|
## Code Reviews
|
|
|
|
All submissions, including submissions by project maintainers, require review. We use standard GitHub pull requests for this purpose:
|
|
|
|
1. Consult [GitHub Help](https://docs.github.com/articles/about-pull-requests/) for information on using pull requests.
|
|
2. Maintainers will review your changes, offer feedback, and approve when ready.
|
|
3. Once approved and all CI checks pass, a project maintainer will merge your PR.
|
|
|
|
---
|
|
|
|
## Development & Contribution Workflow
|
|
|
|
### 1. Setting Up Your Development Environment
|
|
|
|
- **Prerequisites**:
|
|
- Python **3.12+**
|
|
- Android SDK Platform Tools (`adb` available in `PATH`)
|
|
- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
|
|
|
|
- **Clone & Install**:
|
|
```bash
|
|
git clone https://github.com/<your-username>/artemis.git
|
|
cd artemis
|
|
|
|
# Install all dependencies and setup pre-commit hooks
|
|
make setup
|
|
```
|
|
*(Alternatively: `uv sync --dev` and `uv run pre-commit install`)*
|
|
|
|
### 2. Making Changes
|
|
|
|
- Create a descriptive topic branch off `main`:
|
|
```bash
|
|
git checkout -b feat/my-new-feature
|
|
# or
|
|
git checkout -b fix/issue-description
|
|
```
|
|
|
|
- Follow the project's coding and style conventions:
|
|
- **Absolute Imports**: Always use absolute imports (`from artemis.sdk import Agent`). Relative imports are disallowed.
|
|
- **Typing**: Use comprehensive type annotations on all public functions, classes, and methods.
|
|
- **Testing**: Add or update test cases under `tests/` for any modified or new behavior.
|
|
|
|
### 3. Local Verification
|
|
|
|
Before creating a pull request, ensure all linters, type checks, and tests pass:
|
|
|
|
```bash
|
|
# Format code (Ruff)
|
|
make format
|
|
|
|
# Lint code (Ruff)
|
|
make lint
|
|
|
|
# Run static type checker (Pyright)
|
|
make typecheck
|
|
|
|
# Run test suite (Pytest)
|
|
make test
|
|
```
|
|
|
|
### 4. Submitting a Pull Request
|
|
|
|
1. Push your branch to your fork:
|
|
```bash
|
|
git push origin feat/my-new-feature
|
|
```
|
|
2. Open a Pull Request against the `main` branch of the ARTEMIS repository.
|
|
3. Complete the PR template, describing:
|
|
- The motivation behind the change.
|
|
- Any related issue numbers (e.g., `Fixes #42`).
|
|
- How the change was tested (device, emulator, unit tests).
|
|
4. Ensure the CLA check automatically passes on your PR.
|
|
|
|
---
|
|
|
|
## Reporting Bugs and Feature Requests
|
|
|
|
- **Bug Reports**: Open an issue describing the bug, including steps to reproduce, device/emulator specifications, Android version, logs, and screenshots if applicable.
|
|
- **Feature Requests**: Open an issue detailing the use case, proposed API or workflow, and alternatives considered.
|