Metadata-Version: 2.4
Name: fremko
Version: 0.1.5
Summary: A framework for controlling Android devices through LLM agents
Project-URL: Homepage, https://github.com/johnmalek312/fremko
Project-URL: Bug Tracker, https://github.com/johnmalek312/fremko/issues
Author: johnmalek312
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: Topic :: System :: Emulators
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: adbutils==2.9.3
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: anthropic>=0.7.0
Requires-Dist: apkutils==2.0.0
Requires-Dist: arize-phoenix>=11.24.1
Requires-Dist: av>=15.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: llama-index-llms-anthropic>=0.8.4
Requires-Dist: llama-index-llms-google-genai>=0.3.0
Requires-Dist: llama-index-llms-ollama>=0.7.1
Requires-Dist: llama-index-llms-openai-like>=0.5.0
Requires-Dist: llama-index-llms-openai>=0.5.4
Requires-Dist: llama-index>=0.13.2
Requires-Dist: openai>=1.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: posthog==6.0.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typing-extensions
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=11.0.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: safety>=2.0.0; extra == 'dev'
Description-Content-Type: text/markdown

## Fremko

Android device control framework with LLM-powered agents, a WebSocket control plane, and a FastAPI web UI. Run the server on your computer, connect your phone, and automate interactions (tap, swipe, input, launch apps), stream the screen, and drive goals with your preferred LLM.

## Features

- Control Android devices over WebSocket via an on-device accessibility service (Fremko Portal)
- Built-in CLI to run a control server or a combined web UI + HTTP API
- FastAPI endpoints and a minimal web dashboard for live preview and actions
- Pluggable LLM backends (OpenAI, Anthropic, Google GenAI, DeepSeek, Ollama) via `llama-index`

## Prerequisites

- Python 3.10+
- `adb` available in your `PATH`. (Optional)
- An Android device with Developer Options + USB debugging enabled. (Optional)
- Fremko Portal app (see link below) 

## Installation

You have a few options for installing **fremko**:

### Option 1: Recommended (using `uv`)
See [UV_INSTALLATION.md](UV_INSTALLATION.md)

---

### Option 2: Easy (from PyPI)
```bash
pip install fremko
```

---

### Option 3: Development (from source)

```bash
# Requires Python 3.10+
git clone https://github.com/johnmalek312/fremko.git
cd fremko
pip install -e .   # or: uv pip install -e .   # if you are using uv
```

## Quickstart

1) Prepare your Android device
- Enable Developer Options and USB debugging.
- Install and set up the Fremko Portal app: `https://www.github.com/johnmalek312/fremko-portal`
- From your computer, you can also try:
```bash
fremko setup   # installs the APK (if needed) and opens Accessibility settings to enable the Portal
fremko enable  # grants accessibility permission to the Fremko Portal app
fremko ping    # verifies the Portal is installed + reachable
```

2) Start the server on your computer
```bash
fremko web
```
Then open `http://localhost:8080` to view the dashboard.

3) Connect the phone to the server
- In the Fremko Portal app on the phone, set the server URL to `ws://<your-computer-ip>:10001`
- Once connected, the device appears under Clients in the web UI

## CLI

```bash
# Run WebSocket server only
fremko server [--provider GoogleGenAI] [--model models/gemini-2.5-flash] [--ws-port 10001]

# Run server + web UI/HTTP API (recommended)
fremko web [--ws-port 10001] [--http-port 8080] [--host 0.0.0.0]

# ADB helpers
fremko devices
fremko connect <ip:port>
fremko disconnect <ip:port>

# Device readiness
fremko enable                  # gives accessibility permission to the Fremko Portal app on your device
fremko setup [-d SERIAL]       # installs the APK (if needed) and enables the Portal accessibility service
fremko ping  [-d SERIAL]       # verifies the Portal is installed + reachable
```

Common options: `--provider`, `--model`, `--temperature`, `--steps`, `--base_url`, `--api_base`, `--reasoning`, `--reflection`, `--tracing`, `--debug`.

## Web UI and HTTP API

When you run `fremko web`, a FastAPI app serves the dashboard and a simple API:

- `GET /api/clients` — list connected clients
- `GET /api/clients/{id}` — client details
- `POST /api/clients/{id}/goal` — start an agent goal
- `GET /api/clients/{id}/screenshot` — latest screenshot
- `GET /api/clients/{id}/state` — accessibility tree + phone state
- `POST /api/clients/{id}/tap` — tap at coordinates
- `POST /api/clients/{id}/swipe` — straight-line swipe
- `POST /api/clients/{id}/gesture_path` — arbitrary path gesture
- `POST /api/clients/{id}/input` — input text
- `POST /api/clients/{id}/key` — press Android keycode
- `POST /api/clients/{id}/start_app` — start an app
- `POST /api/clients/{id}/stream/{start|update|stop}` — control device-to-server video stream
- `GET /ws/preview/{id}` — WebSocket with JPEG frames for browser preview

Preview streaming is backed by H.264 decoding on the server and JPEG frames to the browser.

## Configuration (LLMs)

LLM selection and configuration are handled through `llama-index` integrations. Set relevant environment variables for your provider:

- Google GenAI: `GOOGLE_API_KEY`
- OpenAI / compatible: `OPENAI_API_KEY`, optional `OPENAI_BASE_URL`
- Anthropic: `ANTHROPIC_API_KEY`
- DeepSeek: `DEEPSEEK_API_KEY`
- Ollama: ensure the local Ollama service is running and configure base URL if needed

Defaults: provider `GoogleGenAI`, model `models/gemini-2.5-flash`.

## Troubleshooting

- No clients in UI: ensure the phone Portal is connected to `ws://<host>:10001` and the server is reachable from the device’s network.
- Accessibility errors: open Accessibility settings on the phone and enable the Fremko Portal service.
- Screenshots/stream not working: check that screen-capture permissions are granted in the Portal, then re-enable if needed.
- ADB device not found: verify `adb devices`, USB debugging, authorization prompts, and cables/drivers.

## License

MIT