Metadata-Version: 2.4
Name: qontinui-api
Version: 0.2.0
Summary: REST API service for Qontinui GUI automation (maintenance mode)
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 :: 7 - Inactive
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: aioboto3 (>=15.5.0,<16.0.0)
Requires-Dist: aiofiles (>=25.1.0,<26.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.124,<0.125)
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 (>=11,<12)
Requires-Dist: psycopg2-binary (>=2.9.9,<3.0.0)
Requires-Dist: pydantic (>=2.12,<3.0)
Requires-Dist: pydantic-settings (>=2.12,<3.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.9)
Requires-Dist: qdrant-client (>=1.11.0,<2.0.0)
Requires-Dist: redis (>=7.1.0,<8.0.0)
Requires-Dist: slowapi (>=0.1.9,<0.2.0)
Requires-Dist: sqlalchemy (>=2.0.43,<3.0.0)
Requires-Dist: torch (>=2.5,<3.0)
Requires-Dist: torchvision (>=0.20,<0.21)
Requires-Dist: uvicorn[standard] (>=0.38,<0.39)
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

> **Maintenance Mode Notice**
>
> This package is in **maintenance mode**. The recommended approach for GUI automation is now the **qontinui-runner** with direct IPC to the qontinui library, which provides better performance and tighter integration.
>
> This package remains available for developers who want HTTP API access to qontinui functionality. No new features will be added, but critical bug fixes may be applied.
>
> **Important:** This package depends on the `qontinui` core library, which is not yet published to PyPI. For local development, install qontinui from source alongside this package.

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.

