Getting started

This walks you from a clean checkout to a working API call. The Russian quickstart covers the same ground; the onboarding guide has the deeper browser-profile setup.

Prerequisites

• Python 3.11+ and Google Chrome (or Chromium) installed.
• A Perplexity Pro login for the browser adapter — not needed for the dry-run call below.

Install and run

1. Install the package with the dev and browser extras:

   pip install -e ".[dev,browser]"

2. Create your environment file and point it at a dedicated Chrome profile (see onboarding for the bootstrap script):

   cp .env.example .env
   # GRACEKELLY_BROWSER_ENABLED=true
   # GRACEKELLY_BROWSER_AUTOMATION_BACKEND=playwright
   # GRACEKELLY_EXECUTION_PROFILE=hybrid
   # GRACEKELLY_BROWSER_PROFILE_DIR=/path/to/dedicated/chrome-profile

3. Start the API:

   python -m uvicorn gracekelly.main:create_app --factory --host 127.0.0.1 --port 8011

Verify it is up

# liveness — process is running
curl -s http://127.0.0.1:8011/healthz/live
# {"status":"ok"}

# readiness — execution profile is loaded
curl -s http://127.0.0.1:8011/api/v1/readiness | grep execution_profile
# "execution_profile": "hybrid"

If readiness reports model_auth_required, the browser profile is not logged in — see onboarding troubleshooting.

Your first call (dry run)

Start with dry_run: true. It exercises the full orchestrate path — validation, planning, response shape — without driving a browser or calling a provider, so it works before any Perplexity login.

curl -s -X POST http://127.0.0.1:8011/api/v1/orchestrate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Say hello.", "dry_run": true}'

{
  "task_id": "…",
  "status": "succeeded",
  "execution_mode": "dry_run",
  "adapter_name": "dry_run",
  "output_text": "…",
  "was_decomposed": false
}

Tip

The dry-run response is the same OrchestrateResponse shape every real call returns — see the API reference for every field.

Your first real call

With a logged-in profile, send a real prompt. smart picks the execution pattern for you (the first browser-backed call cold-starts in ~30s):

curl -s -X POST http://127.0.0.1:8011/api/v1/smart \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2 + 2?", "model": "claude-sonnet-4-6"}'

Where to go next

Execution modes Which endpoint to use — smart, orchestrate, consensus, debate, compare.

API reference Request and response schemas for every endpoint.

Operator runbook Run, monitor, and recover the service day to day.

Architecture overview How a request flows through the orchestrator and adapters.