Metadata-Version: 2.4
Name: agentux
Version: 0.1.4
Summary: Portable multi-agent UX stress tester
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: streamlit==1.47.0
Requires-Dist: playwright==1.54.0
Requires-Dist: openai==1.108.1
Requires-Dist: pydantic==2.11.7
Requires-Dist: PyYAML==6.0.2
Requires-Dist: plotly==6.3.0
Requires-Dist: python-dotenv==1.1.1

# AgentUX

Portable Multi-Agent UX Stress-Tester for local web apps.

## Goal
Install once, then run AgentUX from any project root to audit that project's running app.

## Install
```bash
pip install -e .
playwright install chromium
```

## Install Anywhere
You have three practical options:

1. Direct from local path (dev mode)
```bash
pip install -e /absolute/path/to/ux-tester
```

2. Isolated global CLI via `pipx` (recommended for tool-style usage)
```bash
pipx install /absolute/path/to/ux-tester
```

3. Build wheel and install on another machine
```bash
python -m pip install build
python -m build
pip install dist/agentux-0.1.0-py3-none-any.whl
```

## Use In Any Project
From the target project's root directory:

1. Install AgentUX
```bash
pip install agentux
```

2. Initialize AgentUX (sets key + infers project context/scenario)
```bash
agentux init
```

3. Start your web app (framework-specific)
```bash
# examples:
npm run dev
# or
pnpm dev
# or
python manage.py runserver
```

4. Run AgentUX
```bash
agentux run
```

`agentux run`:
- Requires `.agentux/` to already exist (created by `agentux init`)
- Ensures Playwright Chromium is installed (unless `--skip-browser-install`)
- Starts dashboard and auto-starts audit

Optional:
```bash
agentux run --no-auto
```

Run:
```bash
agentux run
```

Open `http://localhost:8501`.

## Features
- Discovery + dynamic persona synthesis
- Parallel persona audit loops with Playwright
- Structured observability artifacts (screenshots, traces, JSONL logs)
- Streamlit mission-control dashboard
- Final UX friction report (`report.md` + `report.json`)

## Artifact Output
Each run writes under the current project's `.agentux`:

```text
.agentux/artifacts/<run_id>/
  config_snapshot.json
  discovery/
  agents/<agent_id>/
  aggregate/
```

Scenario config is read from `.agentux/scenarios/default.yaml`.
Login credentials are read on-demand from `.agentux/login.yaml` when agents need to fill auth forms.
Use this format:
```yaml
accounts:
  - username: student@example.com
    password: your-password
  - username: teacher@example.com
    password: your-password
```
Inference details are saved to `.agentux/project_profile.json`.
Example:
```yaml
default_scenario:
  id: "default"
  name: "Checkout Flow"
  goal: "Complete a purchase"
  success_assertions:
    - type: "url_contains"
      value: "/checkout/complete"
persona_overrides: {}
```

## Optional Docker Dev Mode
```bash
docker-compose up --build
```

## Notes
- `agentux init` updates `.gitignore` with `.agentux/.env`, `.agentux/login.yaml`, and `.agentux/artifacts/`.
- The engine fails fast on missing API key or unreachable target URL.
- Your target app must already be running before `agentux run`.
