Upload 64 files

.dockerignore

@@ -0,0 +1,25 @@
+# Git
+.git
+.gitignore
+
+# Environment
+.env
+.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.venv/
+venv/
+
+# Documentation / Media
+demo.mp4
+gui_screenshot.png
+n8n_preview.png
+
+# Docker
+docker-compose.yml
+Dockerfile
+.dockerignore

.env

@@ -0,0 +1,7 @@
+# PhantomAPI Configuration
+# Copy this file to .env and adjust values
+API_SECRET_KEY=change-me-to-a-strong-secret
+HOST=0.0.0.0
+PORT=7777
+HEADLESS=true
+BROWSER_TIMEOUT=120000

.env.example

@@ -0,0 +1,7 @@
+# PhantomAPI Configuration
+# Copy this file to .env and adjust values
+API_SECRET_KEY=change-me-to-a-strong-secret
+HOST=0.0.0.0
+PORT=7777
+HEADLESS=true
+BROWSER_TIMEOUT=120000

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+demo.mp4 filter=lfs diff=lfs merge=lfs -text
+n8n_preview.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+venv/
+.venv/
+.env
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.log
+playwright-report/

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,4 @@
+[
+  "tests/test_custom.py::test_custom_api_endpoint[asyncio]",
+  "tests/test_custom.py::test_custom_api_error_handling[asyncio]"
+]

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.11-slim
+
+# Install system dependencies for Playwright/Chromium
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    wget gnupg fonts-liberation libnss3 libatk-bridge2.0-0 libdrm2 \
+    libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
+    libasound2 libpangocairo-1.0-0 libgtk-3-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+	PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt \
+    && python -m playwright install chromium
+
+COPY --chown=user . .
+
+EXPOSE 7860
+
+CMD ["python", "run.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrshibly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,235 @@
----
-title: PutuAPI
-emoji: 🐨
-colorFrom: purple
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: PhantomAPI
+emoji: 👻
+colorFrom: purple
+colorTo: indigo
+sdk: docker
+pinned: false
+---
+
+<div align="center">
+
+# 👻 PhantomAPI
+
+### Turn ChatGPT into a FREE OpenAI-Compatible API
+
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
+[![Playwright](https://img.shields.io/badge/Playwright-2EAD33?style=for-the-badge&logo=playwright&logoColor=white)](https://playwright.dev/)
+[![Docker](https://img.shields.io/badge/Docker-2CA5E0?style=for-the-badge&logo=docker&logoColor=white)](https://docker.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+
+**The invisible proxy that bridges ChatGPT's free web interface with your AI automation workflows.**
+
+[Quick Start](#-quick-start) · [n8n Integration](#-connecting-to-n8n) · [Architecture](#-architecture) · [Docker](#-docker-deployment)
+
+</div>
+
+<div align="center">
+  <video src="demo.mp4" width="800" controls muted autoplay loop></video>
+</div>
+
+---
+
+## 🌟 What is PhantomAPI?
+
+**PhantomAPI** is a high-performance proxy server that makes ChatGPT's free web interface behave like the official OpenAI API. It's designed as a **drop-in replacement** for any tool that speaks the OpenAI protocol — especially **n8n**.
+
+### ✨ Key Features
+
+| Feature | Description |
+|:---|:---|
+| 💸 **Zero API Costs** | Uses ChatGPT's free web interface via headless browser automation |
+| ⚡ **Async Architecture** | Built on FastAPI with a dedicated browser thread for non-blocking requests |
+| 🤖 **AI Agent Support** | Full tool-calling / function-calling support for n8n Agent nodes |
+| 🔒 **API Key Auth** | Protected with Bearer token authentication |
+| 🐳 **Docker Ready** | Deploy in seconds with `docker-compose up` |
+| 🎨 **Built-in GUI** | A sleek dark-mode chat interface for quick testing |
+| 📐 **Clean Architecture** | Proper FastAPI structure — routers, schemas, services, utils |
+
+---
+
+## ⚙️ How It Works
+
+```
+┌──────────┐     HTTP/JSON      ┌──────────────┐     Playwright     ┌──────────────┐
+│   n8n    │ ──────────────────▶ │  PhantomAPI  │ ──────────────────▶ │  ChatGPT     │
+│  (or any │ ◀────────────────── │  (FastAPI)   │ ◀────────────────── │  (Web UI)    │
+│  client) │   OpenAI Schema     │              │   Scrape Response   │              │
+└──────────┘                     └──────────────┘                     └──────────────┘
+```
+
+1. **You send** a standard OpenAI API request to PhantomAPI
+2. **PhantomAPI** formats your messages into a prompt and types it into ChatGPT's web interface using a stealth browser
+3. **ChatGPT responds** on the web page — PhantomAPI scrapes the text
+4. **The response** is formatted back into the official OpenAI JSON schema and returned to you
+
+---
+
+## 🛠️ Quick Start
+
+### Prerequisites
+- **Python 3.10+**
+- **Google Chrome** installed on your system
+
+### 1. Clone & Install
+
+```bash
+git clone https://github.com/mrshibly/phantom-api.git
+cd phantom-api
+pip install -r requirements.txt
+python -m playwright install chromium
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+# Edit .env and set your API_SECRET_KEY
+```
+
+### 3. Run
+
+```bash
+python run.py
+```
+
+The server will start on `http://localhost:7777`.
+
+| Endpoint | Description |
+|:---|:---|
+| `http://localhost:7777/` | Health check |
+| `http://localhost:7777/docs` | Swagger UI (interactive API docs) |
+| `http://localhost:7777/gui` | Chat GUI for quick testing |
+
+---
+
+## 🔌 Connecting to n8n
+
+<div align="center">
+  <img src="n8n_preview.png" width="800" alt="n8n Workflow Example">
+</div>
+
+### Method 1: OpenAI Node (Recommended)
+
+1. In n8n, go to **Credentials → New → OpenAI API**
+2. Set **Base URL** to: `http://127.0.0.1:7777/v1`
+3. Set **API Key** to your `API_SECRET_KEY` from `.env`
+4. Use this credential in any **OpenAI** or **AI Agent** node
+
+> **Docker Tip:** If n8n runs in Docker, use `http://host.docker.internal:7777/v1`
+
+### Method 2: HTTP Request Node
+
+1. Add an **HTTP Request** node
+2. **Method:** `POST`
+3. **URL:** `http://127.0.0.1:7777/v1/chat/completions`
+4. **Authentication:** Header Auth → `Authorization: Bearer YOUR_KEY`
+5. **Body (JSON):**
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "messages": [
+    { "role": "user", "content": "Hello, PhantomAPI!" }
+  ]
+}
+```
+
+---
+
+## 📐 Architecture
+
+```
+phantom-api/
+├── app/
+│   ├── main.py              # App factory, CORS, lifespan
+│   ├── config.py            # Environment-driven settings
+│   ├── dependencies.py      # Auth dependency injection
+│   ├── api/v1/
+│   │   ├── router.py        # Route aggregator
+│   │   ├── chat.py          # POST /v1/chat/completions
+│   │   ├── responses.py     # POST /v1/responses
+│   │   └── models.py        # GET  /v1/models
+│   ├── schemas/
+│   │   ├── chat.py          # Request/Response models
+│   │   └── responses.py     # Responses API models
+│   ├── services/
+│   │   └── browser.py       # Playwright browser engine
+│   └── utils/
+│       ├── prompt.py         # Smart prompt builder
+│       └── parser.py         # Tool-call JSON parser
+├── static/
+│   └── index.html            # Chat GUI
+├── tests/
+│   └── test_health.py        # Endpoint tests
+├── Dockerfile
+├── docker-compose.yml
+├── requirements.txt
+├── .env.example
+└── run.py                    # Entry point
+```
+
+---
+
+## 🐳 Docker Deployment
+
+```bash
+# Build and run
+docker-compose up --build -d
+
+# The server is now running on http://localhost:7777
+```
+
+---
+
+## 🤗 Hugging Face Spaces Deployment
+
+You can deploy PhantomAPI directly to Hugging Face Spaces for free.
+
+1. **Create a New Space**: Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. **Select SDK**: Choose **Docker**
+3. **Choose Template**: Select **Blank** (The existing `Dockerfile` will be used automatically)
+4. **Configure Secrets**:
+   - Go to **Settings → Variables and secrets** in your Space
+   - Add a new **Secret** named `API_SECRET_KEY` with your desired token
+5. **Push Code**:
+   ```bash
+   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+   git push -u hf main
+   ```
+
+PhantomAPI will automatically start on port `7860`.
+
+---
+
+## 🔧 API Reference
+
+### `POST /v1/chat/completions`
+
+Standard OpenAI Chat Completions endpoint. Supports messages, tools, and function calling.
+
+### `POST /v1/responses`
+
+Modern Responses API for newer n8n versions. Accepts `input` (string or messages) and optional `instructions`.
+
+### `GET /v1/models`
+
+Returns available model identifiers (used by n8n's model dropdown).
+
+### `GET /`
+
+Health check — returns server status and version.
+
+---
+
+## 📄 License
+
+This project is open-sourced under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+
+**Built with ❤️ by [mrshibly](https://github.com/mrshibly)**
+
+</div>

app/__init__.py

@@ -0,0 +1,3 @@
+"""PhantomAPI — Application package."""
+
+__version__ = "1.0.0"

app/api/__init__.py

@@ -0,0 +1 @@
+"""PhantomAPI — API package."""

app/api/custom.py

@@ -0,0 +1,31 @@
+"""PhantomAPI — Custom simplified API endpoint."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from app.services.browser import engine
+
+router = APIRouter(tags=["custom"])
+
+class QuickPromptRequest(BaseModel):
+    prompt: str
+
+class QuickPromptResponse(BaseModel):
+    status: str
+    text: str
+
+@router.post("/api", response_model=QuickPromptResponse)
+async def quick_prompt(request: QuickPromptRequest):
+    """Simple API endpoint for quick prompts."""
+    try:
+        # Get response from browser engine
+        response_text = engine.chat(request.prompt)
+        
+        return QuickPromptResponse(
+            status="success",
+            text=response_text
+        )
+    except Exception as e:
+        return QuickPromptResponse(
+            status="error",
+            text=str(e)
+        )

app/api/v1/__init__.py

@@ -0,0 +1 @@
+"""PhantomAPI — API v1 package."""

app/api/v1/chat.py

@@ -0,0 +1,16 @@
+"""PhantomAPI — POST /v1/chat/completions."""
+
+from fastapi import APIRouter, Depends
+
+from app.dependencies import verify_api_key
+from app.schemas.chat import ChatCompletionRequest
+from app.services.chat import process_chat_completion
+
+router = APIRouter()
+
+
+@router.post("/chat/completions", dependencies=[Depends(verify_api_key)])
+async def chat_completions(payload: ChatCompletionRequest):
+    """OpenAI-compatible chat completions endpoint."""
+    data = payload.model_dump()
+    return process_chat_completion(data["messages"], data["model"], data.get("tools"))

app/api/v1/models.py

@@ -0,0 +1,17 @@
+"""PhantomAPI — GET /v1/models."""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/models")
+async def list_models():
+    """Return available models for n8n model dropdown."""
+    return {
+        "object": "list",
+        "data": [
+            {"id": "gpt-4o-mini", "object": "model", "owned_by": "phantom-api"},
+            {"id": "gpt-4o", "object": "model", "owned_by": "phantom-api"},
+        ],
+    }

app/api/v1/responses.py

@@ -0,0 +1,31 @@
+"""PhantomAPI — POST /v1/responses."""
+
+from fastapi import APIRouter, Depends
+
+from app.dependencies import verify_api_key
+from app.schemas.responses import ResponsesRequest
+from app.services.chat import process_responses_api
+
+router = APIRouter()
+
+
+@router.post("/responses", dependencies=[Depends(verify_api_key)])
+async def responses(payload: ResponsesRequest):
+    """Modern Responses API endpoint for newer n8n versions."""
+    data = payload.model_dump()
+    input_data = data.get("input", "")
+
+    # Normalise input to messages list
+    if isinstance(input_data, str):
+        messages = [{"role": "user", "content": input_data}]
+    elif isinstance(input_data, list):
+        messages = input_data
+    else:
+        messages = []
+
+    # Inject system instructions
+    instructions = data.get("instructions", "")
+    if instructions:
+        messages.insert(0, {"role": "system", "content": instructions})
+
+    return process_responses_api(messages, data["model"], data.get("tools"))

app/api/v1/router.py

@@ -0,0 +1,11 @@
+"""PhantomAPI — v1 API router aggregator."""
+
+from fastapi import APIRouter
+
+from app.api.v1 import chat, responses, models
+
+router = APIRouter(prefix="/v1", tags=["v1"])
+
+router.include_router(chat.router)
+router.include_router(responses.router)
+router.include_router(models.router)

app/config.py

@@ -0,0 +1,27 @@
+"""PhantomAPI — Configuration via environment variables."""
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from .env file or environment variables."""
+
+    # --- Security ---
+    API_SECRET_KEY: str = "change-me-to-a-strong-secret"
+
+    # --- Server ---
+    HOST: str = "0.0.0.0"
+    PORT: int = 7860
+
+    # --- Browser Engine ---
+    HEADLESS: bool = True
+    BROWSER_TIMEOUT: int = 120000  # milliseconds
+
+    model_config = {
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "extra": "ignore",
+    }
+
+
+settings = Settings()

app/dependencies.py

@@ -0,0 +1,23 @@
+"""PhantomAPI — Authentication dependencies."""
+
+from fastapi import Request, HTTPException
+from app.config import settings
+
+
+async def verify_api_key(request: Request) -> str:
+    """Validate the Bearer token from the Authorization header.
+
+    Returns the validated key on success, raises 401 on failure.
+    """
+    authorization = request.headers.get("authorization", "")
+
+    if not authorization:
+        raise HTTPException(status_code=401, detail="Missing Authorization header.")
+
+    # Strip "Bearer " prefix
+    token = authorization.replace("Bearer ", "").strip()
+
+    if token != settings.API_SECRET_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API Key.")
+
+    return token

app/main.py

@@ -0,0 +1,56 @@
+"""PhantomAPI — Application factory."""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from app import __version__
+from app.api.v1.router import router as v1_router
+from app.api.custom import router as custom_router
+from app.services.browser import engine
+
+
+@asynccontextmanager
+async def lifespan(application: FastAPI):
+    """Start the browser engine on startup."""
+    engine.start()
+    yield
+
+
+app = FastAPI(
+    title="PhantomAPI",
+    description="A proxy that turns free ChatGPT into an OpenAI-compatible API.",
+    version=__version__,
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(v1_router)
+app.include_router(custom_router)
+
+static_dir = Path(__file__).parent.parent / "static"
+if static_dir.exists():
+    app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+
+@app.get("/", tags=["health"])
+async def health_check():
+    """Health check."""
+    return {"status": "running", "service": "PhantomAPI", "version": __version__}
+
+
+@app.get("/gui", tags=["gui"])
+async def gui_redirect():
+    """Redirect to Chat GUI."""
+    return RedirectResponse(url="/static/index.html")

app/schemas/__init__.py

@@ -0,0 +1 @@
+"""PhantomAPI — Schemas package."""

app/schemas/chat.py

@@ -0,0 +1,28 @@
+"""PhantomAPI — Pydantic schemas for /v1/chat/completions."""
+
+from typing import List, Dict, Any, Optional, Union
+from pydantic import BaseModel, Field
+
+
+class Message(BaseModel):
+    """A single message in the conversation."""
+    role: str = Field(..., description="The role of the message author.")
+    content: Union[str, List[Dict[str, Any]]] = Field(..., description="The content of the message.")
+    name: Optional[str] = Field(default=None, description="Name for tool messages.")
+    tool_calls: Optional[List[Dict[str, Any]]] = Field(default=None, description="Tool calls from assistant.")
+    tool_call_id: Optional[str] = Field(default=None, description="Tool call ID for tool responses.")
+
+
+class ChatCompletionRequest(BaseModel):
+    """Request body for POST /v1/chat/completions."""
+    messages: List[Message] = Field(..., description="The conversation messages.")
+    model: str = Field(default="gpt-4o-mini", description="Model identifier.")
+    tools: Optional[List[Dict[str, Any]]] = Field(default=None, description="Available tools for function calling.")
+    temperature: Optional[float] = Field(default=None, description="Sampling temperature (ignored).")
+    max_tokens: Optional[int] = Field(default=None, description="Max tokens (ignored).")
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [{"messages": [{"role": "user", "content": "Hello!"}], "model": "gpt-4o-mini"}]
+        }
+    }

app/schemas/responses.py

@@ -0,0 +1,15 @@
+"""PhantomAPI — Pydantic schemas for /v1/responses."""
+
+from typing import List, Dict, Any, Optional, Union
+from pydantic import BaseModel, Field
+from app.schemas.chat import Message
+
+
+class ResponsesRequest(BaseModel):
+    """Request body for POST /v1/responses (Modern Responses API)."""
+    input: Union[str, List[Message]] = Field(..., description="The input text or messages.")
+    model: str = Field(default="gpt-4o-mini", description="Model identifier.")
+    tools: Optional[List[Dict[str, Any]]] = Field(default=None, description="A list of tools the model may call.")
+    instructions: Optional[str] = Field(default="", description="System instructions.")
+
+    model_config = {"json_schema_extra": {"examples": [{"input": "Hello!", "model": "gpt-4o-mini"}]}}

app/services/__init__.py

@@ -0,0 +1 @@
+"""PhantomAPI — Services package."""

app/services/browser.py

@@ -0,0 +1,143 @@
+"""PhantomAPI — Browser automation engine.
+
+Launches a persistent headless Chrome instance via Playwright
+and interacts with chatgpt.com to generate responses.
+"""
+
+import asyncio
+import threading
+from app.config import settings
+
+
+class BrowserEngine(threading.Thread):
+    """A dedicated thread that runs an async Playwright browser.
+
+    This avoids blocking the FastAPI event loop while still giving
+    us a persistent browser instance that can handle sequential requests.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(daemon=True)
+        self.loop = asyncio.new_event_loop()
+        self.ready = threading.Event()
+        self.browser = None
+        self.playwright = None
+
+    # ------------------------------------------------------------------
+    # Thread lifecycle
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Thread entry point — start browser and run the event loop forever."""
+        asyncio.set_event_loop(self.loop)
+        self.loop.run_until_complete(self._launch())
+        self.ready.set()
+        print("[PhantomAPI] ⚡ Browser engine ready.")
+        self.loop.run_forever()
+
+    async def _launch(self) -> None:
+        """Launch a stealth Chromium browser."""
+        from playwright.async_api import async_playwright
+
+        print("[PhantomAPI] 🚀 Launching browser...")
+        self.playwright = await async_playwright().start()
+        self.browser = await self.playwright.chromium.launch(
+            headless=settings.HEADLESS,
+            channel="chrome",
+            args=[
+                "--disable-blink-features=AutomationControlled",
+                "--no-sandbox",
+                "--disable-gpu",
+                "--disable-dev-shm-usage",
+                "--disable-setuid-sandbox",
+            ],
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def chat(self, prompt: str) -> str:
+        """Send a prompt to ChatGPT and return the response text.
+
+        This is a blocking call that schedules work on the browser
+        thread's event loop and waits for the result.
+        """
+        if not self.ready.wait(timeout=30) or self.browser is None:
+            raise RuntimeError("Browser engine is not ready. Is Chrome installed?")
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._interact(prompt), self.loop
+        )
+        return future.result(timeout=settings.BROWSER_TIMEOUT // 1000 + 30)
+
+    # ------------------------------------------------------------------
+    # Private — browser interaction
+    # ------------------------------------------------------------------
+
+    async def _interact(self, prompt: str) -> str:
+        """Open a new ChatGPT session, send the prompt, and scrape the reply."""
+        context = await self.browser.new_context(
+            user_agent=(
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/124.0.0.0 Safari/537.36"
+            ),
+            viewport={"width": 1920, "height": 1080},
+        )
+
+        # Hide the webdriver flag so ChatGPT thinks we're a real user
+        await context.add_init_script(
+            "Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"
+        )
+
+        page = await context.new_page()
+
+        try:
+            page.set_default_timeout(settings.BROWSER_TIMEOUT)
+
+            # Navigate to ChatGPT
+            await page.goto("https://chatgpt.com/", wait_until="domcontentloaded")
+
+            # Type the prompt
+            await page.wait_for_selector("#prompt-textarea", timeout=60000)
+            await page.fill("#prompt-textarea", prompt)
+            await asyncio.sleep(0.5)
+            await page.press("#prompt-textarea", "Enter")
+
+            # Wait for the assistant to start responding
+            await page.wait_for_selector(
+                '[data-message-author-role="assistant"]',
+                timeout=settings.BROWSER_TIMEOUT,
+            )
+
+            # Poll until the response stabilises (no new text for ~2 seconds)
+            last_text = ""
+            unchanged_count = 0
+            while unchanged_count < 4:
+                elements = await page.query_selector_all(
+                    '[data-message-author-role="assistant"]'
+                )
+                if elements:
+                    current_text = await elements[-1].inner_text()
+                    if current_text == last_text and current_text.strip():
+                        unchanged_count += 1
+                    else:
+                        last_text = current_text
+                        unchanged_count = 0
+                await asyncio.sleep(0.5)
+
+            return last_text.strip()
+
+        except Exception as exc:
+            print(f"[PhantomAPI] ❌ Browser error: {exc}")
+            raise
+        finally:
+            await page.close()
+            await context.close()
+
+
+# ---------------------------------------------------------------------------
+# Singleton — created once at import time, started in app lifespan
+# ---------------------------------------------------------------------------
+engine = BrowserEngine()

app/services/chat.py

@@ -0,0 +1,108 @@
+"""PhantomAPI — Chat completion service.
+
+All business logic for processing chat requests lives here.
+Route handlers call these functions and return the result directly.
+"""
+
+import time
+import uuid
+
+from app.services.browser import engine
+from app.utils.prompt import format_prompt
+from app.utils.parser import parse_tool_calls
+
+
+def process_chat_completion(messages: list, model: str, tools: list | None = None) -> dict:
+    """Process a chat completion request and return an OpenAI-compatible response."""
+    prompt = format_prompt(messages, tools=tools)
+    start = time.time()
+
+    print(f"[PhantomAPI] 📨 Request ({len(prompt)} chars)")
+    response_text = engine.chat(prompt)
+
+    p_tokens = len(prompt.split())
+    c_tokens = len(response_text.split())
+    tool_calls = parse_tool_calls(response_text) if tools else None
+
+    return _build_chat_response(response_text, tool_calls, model, int(start), p_tokens, c_tokens)
+
+
+def process_responses_api(messages: list, model: str, tools: list | None = None) -> dict:
+    """Process a Responses API request and return the formatted response."""
+    prompt = format_prompt(messages, tools=tools)
+    start = time.time()
+
+    response_text = engine.chat(prompt)
+
+    p_tokens = len(prompt.split())
+    c_tokens = len(response_text.split())
+    tool_calls = parse_tool_calls(response_text) if tools else None
+
+    return _build_responses_response(response_text, tool_calls, model, int(start), p_tokens, c_tokens)
+
+
+# ---------------------------------------------------------------------------
+# Private response builders
+# ---------------------------------------------------------------------------
+
+def _build_chat_response(
+    text: str, tool_calls: list | None, model: str, created: int, p_tokens: int, c_tokens: int
+) -> dict:
+    """Build an OpenAI-compatible chat completion response dict."""
+    response_id = f"chatcmpl-{uuid.uuid4().hex[:29]}"
+    usage = {"prompt_tokens": p_tokens, "completion_tokens": c_tokens, "total_tokens": p_tokens + c_tokens}
+
+    if tool_calls:
+        message = {"role": "assistant", "content": None, "tool_calls": tool_calls}
+        finish_reason = "tool_calls"
+    else:
+        message = {"role": "assistant", "content": text}
+        finish_reason = "stop"
+
+    return {
+        "id": response_id,
+        "object": "chat.completion",
+        "created": created,
+        "model": model,
+        "choices": [{"index": 0, "message": message, "finish_reason": finish_reason}],
+        "usage": usage,
+    }
+
+
+def _build_responses_response(
+    text: str, tool_calls: list | None, model: str, created: int, p_tokens: int, c_tokens: int
+) -> dict:
+    """Build a Responses API response dict."""
+    response_id = f"resp-{uuid.uuid4().hex[:29]}"
+    usage = {"input_tokens": p_tokens, "output_tokens": c_tokens, "total_tokens": p_tokens + c_tokens}
+
+    if tool_calls:
+        output = [
+            {
+                "type": "function_call",
+                "id": tc["id"],
+                "call_id": tc["id"],
+                "name": tc["function"]["name"],
+                "arguments": tc["function"]["arguments"],
+                "status": "completed",
+            }
+            for tc in tool_calls
+        ]
+    else:
+        output = [
+            {
+                "type": "message",
+                "role": "assistant",
+                "content": [{"type": "output_text", "text": text}],
+            }
+        ]
+
+    return {
+        "id": response_id,
+        "object": "response",
+        "created_at": created,
+        "model": model,
+        "status": "completed",
+        "output": output,
+        "usage": usage,
+    }

app/utils/__init__.py

@@ -0,0 +1 @@
+"""PhantomAPI — Utils package."""