Metadata-Version: 2.4
Name: accessibility-intelligence
Version: 1.0.2
Summary: AI agent that scans source code and screenshots for accessibility issues across iOS, Android, and Web
Project-URL: Homepage, https://github.com/shashigupta/accessibility-intelligence
Project-URL: Issues, https://github.com/shashigupta/accessibility-intelligence/issues
Author: Shashi Gupta
License-Expression: MIT
License-File: LICENSE
Keywords: a11y,accessibility,android,ios,mcp,talkback,voiceover,wcag,web
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: numpy>=1.20; extra == 'all'
Requires-Dist: pillow>=9.0; extra == 'all'
Provides-Extra: imaging
Requires-Dist: numpy>=1.20; extra == 'imaging'
Requires-Dist: pillow>=9.0; extra == 'imaging'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Accessibility Intelligence Agent

A terminal-based agent that scans source code for accessibility issues across **Web**, **Android**, and **iOS** platforms.

Built on the accessibility-intelligence skill with a 3-agent architecture:
- **Planner** – detects platforms, gathers files, creates a scan plan
- **Executor** – runs the plan, deduplicates and ranks findings
- **Rules Engine** – platform-specific regex-based accessibility checks

## Quick Start

```bash
# Scan a directory (auto-detects platforms)
python3 -m agent scan ./your-project

# Scan only iOS files
python3 -m agent scan ./src --platform ios

# Preview the plan without scanning
python3 -m agent plan ./your-project

# Generate a saved Markdown report
python3 -m agent report ./your-project --format md

# Generate a JSON report to a specific file
python3 -m agent scan ./src --format json --output report.json

# Scan screenshots for visual accessibility issues
python3 -m agent screenshots ./screenshots --platform ios
```

Or use the wrapper script:

```bash
./a11y-agent scan ./your-project
```

## Inter-Agent Communication

The agent can receive input from, and send output to, other agents using three modes:

### 1. Oneshot Request (Quick Testing)

```bash
# Process a single request from another agent
python3 -m agent serve -r '{"action":"scan","from_agent":"ci-agent","payload":{"path":"./src","platform":"ios"}}'
```

### 2. stdin/stdout Pipe (Pipeline Mode)

```bash
# Pipe from another agent
echo '{"action":"scan","payload":{"path":"./src"}}' | python3 -m agent serve

# Chain agents in a pipeline
planning-agent | python3 -m agent serve | fix-agent
```

### 3. File-Based (Async Multi-Agent)

```bash
# Watch inbox for requests, write responses to outbox
python3 -m agent serve --mode file --inbox ./inbox --outbox ./outbox
```

### 4. Python API (In-Process)

```python
from agent import AccessibilityAgent

a11y = AccessibilityAgent()

# Register downstream agents to receive findings
a11y.on_findings("fix-agent", lambda msg: fix_agent.receive(msg))
a11y.on_findings("jira-agent", lambda msg: jira_agent.create_tickets(msg))

# Scan and auto-dispatch to registered agents
findings = a11y.scan("./src", platform="ios")

# Or process a message from another agent
response = a11y.receive({
    "action": "scan",
    "from_agent": "ci-pipeline",
    "payload": {"path": "./src", "platform": "ios"}
})
```

### Message Schema

**Request:**
```json
{
    "message_id": "optional-uuid",
    "from_agent": "requesting-agent-name",
    "to_agent": "accessibility-intelligence",
    "action": "scan | plan | report | screenshots | health",
    "payload": { "path": "./src", "platform": "ios" },
    "metadata": { "correlation_id": "trace-id" }
}
```

**Response:**
```json
{
    "message_id": "uuid",
    "from_agent": "accessibility-intelligence",
    "to_agent": "requesting-agent-name",
    "status": "success | error",
    "payload": { "findings": [...], "total_issues": 8, "has_critical": true },
    "metadata": { "duration_ms": 1.2, "correlation_id": "trace-id" }
}
```

## Commands

| Command | Description |
|---------|-------------|
| `scan`  | Full pipeline: plan → execute → report (terminal output) |
| `plan`  | Show analysis plan without executing the scan |
| `report`| Scan and save report to `reports/` directory |

## Options

| Flag | Description |
|------|-------------|
| `--platform` | Filter: `web`, `android`, or `ios` |
| `--format` | Output: `terminal`, `json`, or `md` |
| `--output` / `-o` | Custom output file path |
| `--focus` | Focus area hint for the planner |

## Supported Checks

### Web
- Missing `alt` text on images
- Missing `aria-label` on interactive elements
- `<div>` used as button without semantics
- Missing form labels
- Heading order issues
- Missing `lang` attribute

### Android
- Missing `contentDescription`
- Clickable without role
- Missing heading semantics
- Missing state descriptions
- Empty content descriptions

### iOS
- Missing `accessibilityLabel`
- Missing `accessibilityHint`
- Missing `accessibilityTraits` on tap targets
- Images without labels
- Fixed font sizes (Dynamic Type)

## Output

Reports follow the structured schema from SKILL.md — each finding includes:
- `issue_id`, `platform`, `screen`, `issue_type`
- `severity` (critical/high/medium/low)
- `confidence` score
- `evidence` (file, line, code snippet)
- `description` and `recommended_fix`

## Exit Codes

- `0` – No critical/high issues found
- `1` – Critical or high severity issues detected (useful for CI)

## Project Structure

```
hackathon-accessibility/
├── agent/
│   ├── __init__.py        # Public API exports
│   ├── __main__.py        # python -m agent entry point
│   ├── cli.py             # CLI argument parsing and commands
│   ├── config.py          # Configuration constants
│   ├── planner.py         # Planner agent
│   ├── executor.py        # Executor agent
│   ├── reporter.py        # Report generation (terminal/json/md)
│   ├── rules_engine.py    # Platform-specific accessibility rules
│   ├── image_analyzer.py  # Screenshot/UI visual analysis
│   └── protocol.py        # Inter-agent communication protocol
├── mcp_server.py          # MCP server for IDE integration
├── pyproject.toml         # Package config for pip/PyPI
├── mcp-config-example.json
├── references/
│   ├── accessibility-rules.md
│   ├── executor.md
│   └── planner.md
├── reports/               # Generated reports
├── samples/               # Sample files for testing
├── SKILL.md               # Skill definition
├── README.md
└── a11y-agent             # Shell wrapper
```

## Distribution & Installation

### Option 1: MCP Server (Recommended for AI IDEs)

Works with **Kiro, Claude Desktop, Cursor**, and any MCP-compatible tool.

**Install:**
```bash
pip install mcp
```

**Configure your IDE** — add to `~/.kiro/settings/mcp.json` (Kiro) or `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "accessibility-intelligence": {
      "command": "python3",
      "args": ["/path/to/hackathon-accessibility/mcp_server.py"],
      "disabled": false,
      "autoApprove": ["a11y_scan", "a11y_health"]
    }
  }
}
```

Once configured, your IDE can call these tools:
- `a11y_scan` — Scan code for accessibility issues
- `a11y_scan_screenshots` — Analyze screenshots for visual issues
- `a11y_report` — Generate and save a full report
- `a11y_health` — Check agent status

### Option 2: PyPI Package (pip install)

Publish to PyPI so anyone can install with `pip`:

```bash
# Build the package
pip install build
python -m build

# Upload to PyPI
pip install twine
twine upload dist/*

# Then anyone can install:
pip install accessibility-intelligence
a11y-agent scan ./my-project --platform ios
```

### Option 3: VS Code Extension (Marketplace)

For a full VS Code extension with UI panels, see the VS Code Extension API docs.
The extension would spawn the Python agent as a subprocess and display results
in the Problems panel.

### Option 4: GitHub Action (CI/CD)

```yaml
# .github/workflows/a11y.yml
name: Accessibility Check
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install accessibility-intelligence
      - run: a11y-agent scan ./src --platform ios --format json -o a11y-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: accessibility-report
          path: a11y-report.json
```
