Metadata-Version: 2.5
Name: fsq-agent
Version: 0.1.0a1
Summary: Goal-driven FSQ automated testing agent built around OpenAI Agents SDK, Azure OpenAI, harness actions, local utilities, observation, and reporting.
Project-URL: Documentation, https://github.com/microsoft/FSQ#readme
Project-URL: Issues, https://github.com/microsoft/FSQ/issues
Project-URL: Repository, https://github.com/microsoft/FSQ
Author: Microsoft Corporation
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: aiofiles==25.1.0
Requires-Dist: appium-python-client==5.3.1
Requires-Dist: click==8.3.3
Requires-Dist: jinja2==3.1.6
Requires-Dist: openai-agents==0.15.2
Requires-Dist: openai==2.34.0
Requires-Dist: pillow==12.3.0
Requires-Dist: playwright==1.60.0
Requires-Dist: pydantic-settings==2.14.2
Requires-Dist: pydantic==2.13.3
Requires-Dist: pywinauto==0.6.9
Requires-Dist: pyyaml==6.0.3
Requires-Dist: ruamel-yaml==0.18.16
Requires-Dist: structlog==25.5.0
Requires-Dist: uiautomator2==3.5.2
Provides-Extra: dev
Requires-Dist: pre-commit==4.6.1; extra == 'dev'
Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
Requires-Dist: pytest==9.0.3; extra == 'dev'
Requires-Dist: ruff==0.16.1; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
    <img alt="FSQ — Fully Self Quality" src="docs/assets/logo-light.svg" width="320">
  </picture>
</p>

<h3 align="center">
  An evidence-first agent harness for replayable, verifiable AI UI automation.
</h3>

<p align="center">
  <a href="https://github.com/microsoft/FSQ/actions/workflows/ci.yml"><img src="https://github.com/microsoft/FSQ/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <!-- <a href="https://pypi.org/project/fsq-agent/"><img src="https://img.shields.io/pypi/v/fsq-agent?color=blue" alt="PyPI"></a> -->
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#why-fsq">Why FSQ</a> •
  <a href="#supported-platforms">Platforms</a> •
  <a href="docs/">Documentation</a> •
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

<!-- TODO: Replace with actual demo GIF showing a full FSQ run -->
<!-- GIF should show: goal input → agent executing → evidence captured → verification → YAML generated -->
<p align="center">
  <img src="docs/assets/demo.gif" alt="FSQ Demo: goal → execution → evidence → verification → replay YAML" width="720">
</p>

---

## Why FSQ?

<table>
<tr>
<td width="33%" align="center">

**Evidence-First**

Every step captures screenshots, UI snapshots, and action traces. You verify through evidence, not agent self-reports.

</td>
<td width="33%" align="center">

**Replayable**

Successful AI runs auto-generate strict YAML. Replay deterministically without LLM — same harness, same evidence, zero flakiness.

</td>
<td width="33%" align="center">

**Verifiable**

Results are judged by an evidence-based verifier, not the agent claiming success. Auditable, trustworthy, CI-ready.

</td>
</tr>
</table>

> **Other AI agents say "I'm done." FSQ shows you the proof.**

---

## See It in Action

```
┌──────────────────────────────────────────────────────────────────────┐
│ $ cd /path/to/workspaces/web-demo                                   │
│ $ fsq case create --platform web                                    │
│     --goal "Search for FSQ on Bing"                                │
├──────────────────────────────────────────────────────────────────────┤
│  ► Planning: 3 key actions identified                                │
│  ► Step 1: startBrowser          📸 screenshot + UI snapshot         │
│  ► Step 2: navigateTo bing.com   📸 screenshot + UI snapshot         │
│  ► Step 3: typeText "FSQ"        📸 screenshot + UI snapshot         │
│  ► Step 4: pressKey Enter        📸 screenshot + UI snapshot         │
│  ► Verification: PASSED ✅ (evidence-based)                          │
│  ► Recording manifest → .fsq/runs/web/<run-id>/recording.json       │
│  ► Replayable YAML → .fsq/runs/web/<run-id>/recorded.fsq.yaml       │
└──────────────────────────────────────────────────────────────────────┘
```

---

## What Can FSQ Do?

<table>
<tr>
<th></th>
<th>Dynamic Mode 🤖<br><sub>AI-driven exploration</sub></th>
<th>Strict Mode 🔁<br><sub>Deterministic replay</sub></th>
</tr>
<tr><td><b>AI explores and operates your app</b></td><td align="center">✅</td><td align="center">—</td></tr>
<tr><td><b>Evidence captured on every step</b></td><td align="center">✅</td><td align="center">✅</td></tr>
<tr><td><b>Auto-generates replayable YAML</b></td><td align="center">✅</td><td align="center">—</td></tr>
<tr><td><b>Deterministic regression execution</b></td><td align="center">—</td><td align="center">✅</td></tr>
<tr><td><b>AI-powered visual assertions</b></td><td align="center">✅</td><td align="center">✅</td></tr>
<tr><td><b>Runs without LLM</b></td><td align="center">—</td><td align="center">✅</td></tr>
</table>

**The Dual Loop:** AI explores → evidence proves it worked → strict YAML locks it down → replay catches regressions.

---

## Quick Start

### 1. Install

```bash
pip install fsq-agent
```

<details>
<summary><b>Using uv (recommended for development)</b></summary>

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --extra dev
```

</details>

The default installation includes the Python dependencies for Android, Web, Windows, and macOS. FSQ does not use platform extras. Applications, browsers, devices, and host services such as Appium remain system prerequisites.

### 2. Initialize a Workspace

```bash
mkdir web-demo && cd web-demo
fsq init --platform web --browser-channel chrome
```

`init` uses the exact current directory as the Workspace root and derives the Workspace name from that directory. It initializes one platform per invocation. To configure another platform in the same Workspace, run `init` again from the same directory:

```bash
cd /path/to/workspaces/web-demo

# Initialize Web. The executable path is optional when one matching browser is discoverable.
fsq init \
  --platform web \
  --browser-channel chrome

# Add Android to the same registered workspace.
fsq init \
  --platform android \
  --app-id com.example.app
```

Platform target options are:

| Platform | `init` target options |
|---|---|
| Android | `--app-id APP_ID` (required) |
| Web | `--browser-channel CHANNEL` (required), optional `--browser-executable-path FILE` |
| Windows | `--app-path PATH` (required), plus optional `--window-title-re` and `--launch-args` |
| macOS | `--bundle-id` or `--app-path` (at least one required) |

Repeating an equal platform configuration returns `unchanged`. If its target or private environment mapping differs, pass `--update-existing` to replace only that platform's target and `--env NAME=VALUE` entries. Use `fsq --output json init ...` or `--output jsonl` for machine output. `init` checks readiness but never installs Driver/Runtime packages or system prerequisites.

Run `fsq doctor` from the exact Workspace root to inspect configured-platform readiness. Commands do not search parent directories or migrate legacy `.fsq/config.yaml` and `.fsq-agent-workspace` layouts.

### 3. Configure a Provider

Configure and inspect the user-level Provider from any directory:

```bash
fsq providers configure github_copilot
fsq providers status
```

| Provider | Setup |
|---|---|
| GitHub Copilot GPT | Model name and GitHub device-code authentication |
| Azure GPT | Azure OpenAI-compatible base URL, model/deployment name, and API key |

Provider configuration is stored under `~/.fsq` and shared with the Control Plane UI. Azure OpenAI can be configured with `fsq providers configure azure_openai`.

### 4. Create and Test Cases

```bash
cd /path/to/workspaces/web-demo

# AI-driven exploration with evidence and a Run-local candidate Case
fsq case create --platform web \
  --goal "Open https://www.bing.com, search for 'FSQ automation', verify results appear."
```

```bash
# Deterministic execution of an existing Case
fsq case test --platform web path/to/case.fsq.yaml

# Execute once, then ask AI to analyze the persisted execution facts
fsq case test --platform web --suggest path/to/case.fsq.yaml
```

Every execution writes evidence and reports under `.fsq/runs/<platform>/<run-id>/`. Suggestions and candidate Cases are Run-local and never overwrite the source Case or `cases/<platform>`. Inspect history with `fsq runs list`, `fsq runs show RUN_ID`, and `fsq runs logs RUN_ID`. `fsq runs show RUN_ID --open` builds and opens an offline static HTML report.

### Control Plane

Launch the local browser Control Plane for multi-platform workspace management, platform readiness, target and case discovery, Explore runs, Strict Replay, and live evidence:

```bash
fsq ui
```

It listens on `127.0.0.1:8879` and opens a browser by default. Use `--host`, `--port`, and `--no-open-browser` to override those defaults. A wheel installation includes the compiled frontend and needs no Node.js runtime. From a source checkout, run `npm ci && npm run build` before starting the Control Plane.

---

## Supported Platforms

<table>
<tr>
<th>Platform</th>
<th>Backend</th>
<th>Install</th>
</tr>
<tr>
<td>🌐 <b>Web</b></td>
<td>Playwright</td>
<td>Included with <code>fsq-agent</code></td>
</tr>
<tr>
<td>📱 <b>Android</b></td>
<td>uiautomator2</td>
<td>Included with <code>fsq-agent</code></td>
</tr>
<tr>
<td>🖥️ <b>Windows</b></td>
<td>pywinauto</td>
<td>Included with <code>fsq-agent</code></td>
</tr>
<tr>
<td>🍎 <b>macOS</b></td>
<td>Appium Mac2</td>
<td>Included with <code>fsq-agent</code></td>
</tr>
</table>

All platforms share the same `HarnessInterface`, evidence model, and FSQ YAML format. A registered workspace may configure one or more platforms independently:

```text
<workspace-root>/
  .fsq/config/config.<platform>.yaml
  cases/<platform>/
  knowledge/<platform>/
  .fsq/runs/<platform>/
```

Workspace commands use the exact current directory as the registered Workspace root. `fsq doctor` checks all configured platforms; `fsq case create/test` select a platform; `fsq runs` queries Workspace history across all platforms unless filtered. `fsq ui` starts the browser Control Plane and uses its own Workspace selection.

<details>
<summary><b>Platform setup details</b></summary>

**Web** — Set the browser executable in `.fsq/config/config.web.yaml`:
```yaml
target:
  browser_executable_path: /usr/bin/google-chrome
```

**Android** — Set the app ID in `.fsq/config/config.android.yaml`, then select a connected ADB device per run:
```yaml
target:
  app_id: com.example.app
```
```bash
cd /path/to/workspaces/my-workspace
fsq case create --platform android --goal "Open the app"
```
Device selection and readiness are resolved from the initialized Workspace and connected-device state.

**Windows** — Keep `backend_kind` in the repository preset `config.windows.yaml`; set app-specific values in `.fsq/config/config.windows.yaml`:
```yaml
target:
  app_path: C:\Program Files\MyApp\app.exe
  window_title_re: .*MyApp.*
```

**macOS** — Keep `appium_server_url` in the repository preset `config.macos.yaml`; set the app identity in `.fsq/config/config.macos.yaml`:
```yaml
target:
  bundle_id: com.example.app
```

</details>

---

## How It Works

<p align="center">
  <img src="docs/assets/fsq-agent-architecture-v2.png" alt="FSQ Architecture: Dual Loop, Shared Harness, Knowledge System, and Debug System" width="720">
</p>

**The Dual Loop in a nutshell:**
- **Dynamic (AI)** → LLM agent explores → evidence captured at every step → replayable YAML generated
- **Strict (Replay)** → replays YAML deterministically (no LLM) → evidence captured → pass/fail

---

## Compared To...

| | **FSQ** | Browser Use | Midscene.js | Playwright | Appium |
|---|---|---|---|---|---|
| **Evidence per step** | ✅ screenshots + UI snapshots + traces | ❌ | ❌ | ❌ | ❌ |
| **AI → Replay YAML** | ✅ auto-generated strict cases | ❌ | ❌ | Codegen (manual) | ❌ |
| **Verification** | Evidence-based verifier | Agent self-report | Vision assert | Manual assertion | Manual assertion |
| **Cross-platform** | Web + Android + Windows + macOS | Web only | Web + Mobile | Web only | Multi (different APIs) |
| **Runs without LLM** | ✅ Strict mode | ❌ | ❌ | ✅ | ✅ |
| **Extensible harness** | Protocol-based plugin system | ❌ | ❌ | ❌ | Driver plugins |

---

## Documentation

| Resource | Description |
|---|---|
| [Architecture Overview](docs/fsq-agent-architecture-v2.md) | Dual Loop design and module structure |
| [Platform Setup](docs/) | Detailed per-platform configuration |
| [FSQ YAML Reference](docs/) | DSL syntax, lifecycle hooks, replay semantics |
| [Harness Development Guide](docs/) | Build a new platform harness |
| [Roadmap](ROADMAP.md) | Product direction and planned phases |
| [Governance](GOVERNANCE.md) | Roles, decisions, and maintainer responsibilities |

<!-- TODO: Set up docs site (mkdocs-material + GitHub Pages) -->

---

## Contributing

We welcome contributions! FSQ is designed to be extended.

```bash
git clone https://github.com/microsoft/FSQ.git && cd FSQ
uv sync --extra dev
npm ci && npm run build
uv run python -m pytest
```

**Ways to contribute:**

| Path | For whom |
|---|---|
| 🐛 Report bugs / suggest features | Everyone |
| 📝 Improve docs and examples | Beginners welcome |
| 🧪 Add FSQ YAML test cases | QA engineers |
| 🔌 Build a new platform harness | Platform experts |
| ⚡ Improve agent / verification | AI engineers |

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide and contributor growth path. Project decisions and role progression follow [GOVERNANCE.md](GOVERNANCE.md).

<!-- TODO: Add "good first issue" link once issues are created -->

---

## License

[MIT](LICENSE) — Copyright (c) Microsoft Corporation.

---

<p align="center">
  <sub>Built with ❤️ by the FSQ team at Microsoft</sub>
</p>
