Metadata-Version: 2.4
Name: buildroid
Version: 1.2.0
Summary: Automation of Android Project Building with LLMs
Author-email: Jaehyeon Kim <jk7404@nyu.edu>
Project-URL: Homepage, https://github.com/jk7404/builDroid
Project-URL: Bug Tracker, https://github.com/jk7404/builDroid/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.9.0
Requires-Dist: async-timeout==4.0.3
Requires-Dist: blis==1.3.0
Requires-Dist: cachetools==5.5.2
Requires-Dist: catalogue==2.0.10
Requires-Dist: certifi==2025.4.26
Requires-Dist: charset-normalizer==3.4.2
Requires-Dist: click==8.2.1
Requires-Dist: cloudpathlib==0.21.1
Requires-Dist: colorama==0.4.6
Requires-Dist: confection==0.1.5
Requires-Dist: cymem==2.0.11
Requires-Dist: distro==1.9.0
Requires-Dist: docker==7.1.0
Requires-Dist: debugpy==1.8.14
Requires-Dist: et-xmlfile==2.0.0
Requires-Dist: exceptiongroup==1.3.0
Requires-Dist: google-api-core==2.25.0
Requires-Dist: google-auth==2.40.2
Requires-Dist: google-genai==1.18.0
Requires-Dist: greenlet==3.2.2
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: idna==3.10
Requires-Dist: jinja2==3.1.6
Requires-Dist: jiter==0.10.0
Requires-Dist: jsonpatch==1.33
Requires-Dist: jsonpointer==3.0.0
Requires-Dist: jsonschema==4.24.0
Requires-Dist: langchain==0.3.25
Requires-Dist: langchain-core==0.3.63
Requires-Dist: langchain-text-splitters==0.3.8
Requires-Dist: langcodes==3.5.0
Requires-Dist: langsmith==0.3.43
Requires-Dist: language-data==1.3.0
Requires-Dist: marisa-trie==1.2.1
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: markupsafe==3.0.2
Requires-Dist: mdurl==0.1.2
Requires-Dist: murmurhash==1.0.13
Requires-Dist: numpy==2.2.6
Requires-Dist: openai==1.82.1
Requires-Dist: openpyxl==3.1.5
Requires-Dist: orjson==3.10.18
Requires-Dist: packaging==24.2
Requires-Dist: pandas==2.2.3
Requires-Dist: preshed==3.0.10
Requires-Dist: pyasn1==0.6.1
Requires-Dist: pyasn1-modules==0.4.2
Requires-Dist: pydantic==2.11.5
Requires-Dist: pydantic-core==2.33.2
Requires-Dist: pygments==2.19.1
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-dotenv==1.1.0
Requires-Dist: pytz==2025.2
Requires-Dist: pyyaml==6.0.2
Requires-Dist: requests==2.32.3
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: rich==14.0.0
Requires-Dist: rsa==4.9.1
Requires-Dist: shellingham==1.5.4
Requires-Dist: six==1.17.0
Requires-Dist: smart-open==7.1.0
Requires-Dist: sniffio==1.3.1
Requires-Dist: spacy==3.8.7
Requires-Dist: spacy-legacy==3.0.12
Requires-Dist: spacy-loggers==1.0.5
Requires-Dist: sqlalchemy==2.0.41
Requires-Dist: srsly==2.5.1
Requires-Dist: tenacity==9.1.2
Requires-Dist: thinc==8.3.6
Requires-Dist: tqdm==4.67.1
Requires-Dist: typer==0.16.0
Requires-Dist: typing-extensions==4.13.2
Requires-Dist: typing-inspection==0.4.1
Requires-Dist: tzdata==2025.2
Requires-Dist: urllib3==2.4.0
Requires-Dist: wasabi==1.1.3
Requires-Dist: weasel==0.4.1
Requires-Dist: websockets==15.0.1
Requires-Dist: wrapt==1.17.2
Requires-Dist: zstandard==0.23.0
Dynamic: license-file

# BuilDroid

[![PyPI version](https://badge.fury.io/py/buildroid.svg)](https://badge.fury.io/py/buildroid)
[![PyPI license](https://img.shields.io/pypi/l/ansicolortags.svg)](https://pypi.python.org/pypi/buildroid)
[![PyPI status](https://img.shields.io/pypi/status/ansicolortags.svg)](https://pypi.python.org/pypi/buildroid)

⚡ Clone, build, and generate debugging APKs for Android projects using LLM-powered automation.

**BuilDroid** is a Python package that leverages Large Language Models (LLMs) to automatically clone any Android project hosted on GitHub, configure it, and **build the debugging `.apk`** file. This enables faster evaluation, performance testing, reverse engineering, or security analysis of Android applications. The building process happens in an isolated Docker container.

## 🚀 Features

- 🔗 Clone any Android GitHub repository.
- ⚙️ Auto-configure Gradle build for debugging.
- 🤖 LLM-guided build troubleshooting and error recovery.
- 📦 Outputs ready-to-install **debugging APK**.
- 🧪 Supports workflows for performance evaluation and static/dynamic analysis.

## 📦 Installation

```bash
pip install buildroid
```

## 📦 Dev Container Setup  

To setup in a VSCode Dev Container:  
1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.  
2. Clone this repository. 
3. Open the repository in VSCode, and it will prompt you to reopen in the dev container. Alternatively, use a command to open the current folder in a dev container.

## ✅ Requirements

* Python 3.10+
* Git installed and accessible from terminal
* OpenAI API key (or other LLM provider) for LLM access.

## ⚙️ LLM Configuration

`builDroid` uses an LLM backend for build assistance. To use it:

1. Obtain your API key from OpenAI or compatible provider.
2. Set your API key as a .env file:

```.env
API_KEY=<your-api-key-here>
BASE_URL=<your-base-url-here>
LLM_MODEL=<your-llm-model-here>
```

`BASE_URL` and `LLM_MODEL` are optional. If not provided, `builDroid` will use OpenAI's `gpt-4.1-mini-2025-04-14`.
For example, if you put 'https://generativelanguage.googleapis.com/v1beta/' as your base url, `builDroid` will access Google AI's `gemini-2.0-flash-lite`.
If you want to use other providers, you have to provide the base url and the LLM model in `.env`.

3. (Optional) builDroid's primary goal is to successfully execute `./gradlew assembleDebug`. To change its goals, create a `ai_settings.yaml` file in the working directory. The example file is in the source code.

## 🖥️ Usage

### CLI Usage

```bash
buildroid build https://github.com/user/project # Run on a single repository
buildroid build repos.txt # Run on a list of repositories from a file
buildroid build local_path --local # Run with a local repository
```
```bash
buildroid clean # Clean test results
```

### Advanced Options for Builds

* `-n`, `--num`: Specify cycle limit (max. number of commands to execute)
* `-c`, `--conv`: Enable conversation mode (API works with conversation models)
* `-k`, `--keep-container`: Keep container after build (builDroid removes container by default)
* `-l`, `--local`: Build from a local repository (Provide local path instead of Github link)

### Python Usage

```python
import builDroid

source = "https://github.com/user/project"

builDroid.utils.api_token_setup() # This function will setup the environment variables from .env file

builDroid.process_repository(repo_source=source)
# args: 
# repo_source: str,
# cycle_limit: int = 40,
# conversation: bool = False,
# extract_project: bool = True,
# override_project: bool = False,
# keep_container: bool = False,
# user_retry: bool = False,
# local_path: bool = False,
# project_name: str = None

builDroid.utils.api_token_reset() # This function will reset the environment variables
```

## 🛠️ Troubleshooting

If the build fails, `builDroid` will attempt to:

1. Analyze the error output.
2. Query the LLM for common solutions.
3. Retry the build with suggested fixes.

> ❗ **Note:** Some complex/outdated builds may still require manual intervention.

## 🏗️ Roadmap

* [ ] Integration with emulator for automated APK testing

## 🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss.

## 📜 License

MIT License. See `LICENSE` for details.

## 🙏 Acknowledgments

* OpenAI for LLM API
* ExecutionAgent
