Metadata-Version: 2.4
Name: qontinui-api
Version: 0.1.1
Summary: REST API service for Qontinui GUI automation
License: MIT
Keywords: gui,automation,api,fastapi,qontinui
Author: Joshua Spinak
Author-email: jspinak@alum.mit.edu
Requires-Python: >=3.12,<3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Dist: alembic (>=1.13.0,<2.0.0)
Requires-Dist: cors (>=1.0.1,<2.0.0)
Requires-Dist: easyocr (>=1.7.0,<2.0.0)
Requires-Dist: email-validator (>=2.3.0,<3.0.0)
Requires-Dist: fastapi (>=0.104.1,<0.105.0)
Requires-Dist: numpy (>=1.26,<2.0)
Requires-Dist: opencv-python (>=4.9,<5.0)
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: pillow (>=10.2,<11.0)
Requires-Dist: psycopg2-binary (>=2.9.9,<3.0.0)
Requires-Dist: pydantic (>=2.5.0,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Requires-Dist: python-jose[cryptography] (>=3.3.0,<4.0.0)
Requires-Dist: python-multipart (>=0.0.6,<0.0.7)
Requires-Dist: qontinui (>=0.1.0,<0.2.0)
Requires-Dist: sqlalchemy (>=2.0.43,<3.0.0)
Requires-Dist: uvicorn[standard] (>=0.24.0,<0.25.0)
Project-URL: Documentation, https://github.com/qontinui/qontinui-api#readme
Project-URL: Homepage, https://github.com/qontinui/qontinui-api
Project-URL: Repository, https://github.com/qontinui/qontinui-api
Description-Content-Type: text/markdown

# Qontinui API Service

REST API service that exposes real qontinui library image recognition capabilities for web-based testing.

## Features

- **Real Qontinui Pattern Matching**: Uses actual qontinui Find operations
- **State Detection**: Detect which states are present in screenshots
- **Location Validation**: Validate locations with image-relative positioning
- **Web-Friendly**: Base64 image support for easy browser integration

## Endpoints

### Vision Operations

#### POST /find
Find a single template match in a screenshot using qontinui's real pattern matching.

```json
{
  "screenshot": "base64_image_data",
  "template": "base64_image_data",
  "similarity": 0.8,
  "search_region": {"x": 0, "y": 0, "width": 100, "height": 100}
}
```

#### POST /find_all
Find all template matches in a screenshot.

#### POST /detect_states
Detect which states from a list are present in a screenshot.

```json
{
  "screenshot": "base64_image_data",
  "states": [...],
  "similarity": 0.8
}
```

#### POST /validate_location
Validate if a location is accessible, with optional image-relative positioning.

## Installation

1. Install Python dependencies:
```bash
pip install -r requirements.txt
```

2. Start the service:
```bash
./start.sh
```

Or manually:
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

## API Documentation

When running, interactive API documentation is available at:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## Integration with Frontend

The API accepts base64-encoded images and returns JSON responses with match regions, scores, and detection results. Perfect for integration with the qontinui-web frontend for visual testing and validation.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

## License

This project is open source. See the [LICENSE](LICENSE) file for details.

## Contact

For questions or issues, please contact jspinak@hotmail.com or open an issue on GitHub.

