https://github.com/bazanadriana/robot-driver-api
FastAPI + Playwright automation service that opens Amazon, finds a product, and returns live price/title via an HTTP endpoint.
https://github.com/bazanadriana/robot-driver-api
api automation browser-automation fastapi playwright python web-scraping
Last synced: about 2 months ago
JSON representation
FastAPI + Playwright automation service that opens Amazon, finds a product, and returns live price/title via an HTTP endpoint.
- Host: GitHub
- URL: https://github.com/bazanadriana/robot-driver-api
- Owner: bazanadriana
- Created: 2025-10-29T01:32:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-10-29T02:54:48.000Z (8 months ago)
- Last Synced: 2025-10-29T04:27:20.741Z (8 months ago)
- Topics: api, automation, browser-automation, fastapi, playwright, python, web-scraping
- Language: Python
- Homepage:
- Size: 35.5 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🤖 Robot Driver API
A compact web automation service built with **FastAPI** and **Playwright**.
It launches a real Chromium browser, navigates to **Amazon**, searches for a given product, opens the first result, extracts the **title** and **price**, and returns them as JSON via an HTTP API.
---
## 🧩 Setup & Usage
### 1️⃣ Environment Setup
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
playwright install chromium
````
If Playwright gives sandbox errors on macOS, the code already uses `headless=False` for interactive runs.
---
### 2️⃣ Environment Variables
Create a `.env` file in the project root if you want to store credentials or API keys:
```bash
OPENAI_API_KEY=sk-...
AMAZON_EMAIL=you@example.com
AMAZON_PASSWORD=...
```
OpenAI is optional — the project works without it.
`ask_llm.py` is available for an AI planner extension (Optional Challenge 1).
---
### 3️⃣ Run the Server
```bash
uvicorn app:app --host 0.0.0.0 --port 8000
```
Your API will be live at:
```
http://localhost:8000
```
Interactive Swagger docs:
```
http://localhost:8000/docs
```
---
### 4️⃣ Example Request
Send a POST request to `/run` with a JSON body that includes the product query.
**Option A – curl**
```bash
curl -X POST "http://localhost:8000/run" \
-H "Content-Type: application/json" \
-d '{"query": "Apple AirPods Pro"}'
```
**Option B – Swagger UI**
1. Visit [http://localhost:8000/docs](http://localhost:8000/docs)
2. Expand `POST /run`
3. Click **Try it out** and send:
```json
{
"query": "Apple AirPods Pro"
}
```
**Example Response**
```json
{
"status": "SUCCESS",
"query": "Apple AirPods Pro",
"title": "Apple AirPods Pro (2nd Generation) ...",
"price": "$197.99",
"url": "https://www.amazon.com/dp/B0XXXXX"
}
```
---
## ⚙️ Internals
`src/agent_driver.py` contains the automation logic:
* Launches Chromium
* Navigates to Amazon
* Searches for the given query
* Opens the first product result
* Extracts the title and price
* Returns structured data
`app.py` exposes this via a `/run` FastAPI endpoint.
`src/robot.py` provides Playwright helpers (login, price extraction, etc.).
`src/ask_llm.py` supports optional LLM/MCP integration for AI-driven planning.
---
## 📁 Project Layout
```
robot-driver/
├─ app.py # FastAPI API server
├─ requirements.txt # Dependencies
├─ README.md # This file
├─ .env # Environment config (optional)
├─ debug.html # Saved Amazon page snapshot if blocked
├─ src/
│ ├─ agent_driver.py # Core orchestration logic
│ ├─ robot.py # Browser utilities
│ ├─ ask_llm.py # Optional AI/MCP module
```
---
## 🔒 Notes / Production Tips
For deployment:
* Run headless Chromium in Docker
* Add authentication and rate limiting
* Handle Amazon CAPTCHA pages gracefully
* Deploy with Render, Railway, or Replit for public testing
For this challenge:
✅ Functional browser agent
✅ `/run` network-accessible API
✅ Clear setup + docs
✅ Demonstrates automation packaged as a web service
---
## 🧠 Evaluation Summary
| **Criteria** | **Skill Demonstrated** | **Result** |
| ----------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| **Required Core (Section 1)** | Core Python, Playwright automation, software reliability | ✅ Fully functional |
| **Optional Challenge 1 (AI + MCP)** | AI agent architecture, structured communication | ⚙️ Ready for LLM integration via `ask_llm.py` |
| **Optional Challenge 2 (Sharing)** | API design, web service, deployment readiness | ✅ Complete |
| **Code Quality** | Clean structure, readable code, clear `README.md`, Git usage | ✅ High |
---
## 🏁 Submission Summary
This project delivers a fully functional **Playwright + FastAPI** agent packaged as a reusable web service.
The `/run` endpoint demonstrates **automation, API design, and deployment readiness**.
It includes clean modular code, documentation, and optional hooks for AI/MCP integration.
> 🎯 Run locally or deploy online — everything needed for evaluation is included.
```
---
📜 License
MIT © 2025
👤 Author
Adriana Bazan
GitHub: @bazanadriana
```