fsq-agent 0.1.0a1__tar.gz

fsq_agent-0.1.0a1/.gitignore

@@ -0,0 +1,38 @@
+.venv/
+.DS_Store
+**/.DS_Store
+.vscode/*
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.env
+config.local.yaml
+cases/
+.fsq-agent-workspace/
+logs/
+log/
+output/
+reports/
+screenshots/
+dist/
+*.egg-info/
+knowledge/*
+!knowledge/skills/
+!knowledge/skills/**
+node_modules/
+.frontend-dist/
+fsq_agent/adapters/control_plane/playground/static/
+fsq_agent/adapters/control_plane/static/
+fsq_agent/resources/
+
+
+# Private/local planning material. Do not commit.
+docs/fsq-opensource-strategy.md
+docs/fsq-benchmark-metrics.md
+docs/README-draft.md
+docs/superpowers/
+private/
+docs/private/
+*.internal.md
+*.private.md

fsq_agent-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fsq_agent-0.1.0a1/PKG-INFO

@@ -0,0 +1,411 @@
+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>