Skip to main content

​
Get started with Haggle

This guide will get you from zero to running Haggle in under 10 minutes.

​
Prerequisites

Python 3.x

Required for backend service

Node.js 16+

Required for frontend (optional)

xAI API Key

Get from xAI Console

Supabase Account

Free tier available at supabase.com

​
Quick Start with CLI

The fastest way to see Haggle in action is using the CLI demo mode:
1

Install dependencies

pip install -r requirements.txt
2

Set up environment

Create a config.py file with your API keys:
config.py
XAI_API_KEY = "your-xai-api-key"
OPENAI_API_KEY = "your-openai-api-key"
SUPABASE_URL = "your-supabase-url"
SUPABASE_KEY = "your-supabase-key"
MAX_PROVIDERS = 5
3

Set up Supabase database

Run this SQL in your Supabase SQL editor to create the providers table:
CREATE TABLE providers (
  id BIGSERIAL PRIMARY KEY,
  service_provider TEXT NOT NULL,
  phone_number TEXT,
  context_answers TEXT,
  house_address TEXT,
  zip_code TEXT,
  max_price NUMERIC,
  job_id TEXT,
  minimum_quote NUMERIC,
  negotiated_price NUMERIC,
  call_status TEXT,
  call_transcript TEXT,
  problem TEXT,
  raw_result JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
4

Run the demo

python cli.py --demo
This will run through a complete demo workflow:
  1. Submit a service request (e.g., “fix my leaky faucet”)
  2. AI infers the task type (plumber)
  3. Generates clarifying questions
  4. Searches for local providers
  5. Saves results to database

​
Quick Start with API

To run the full API server:
1

Start the backend

uvicorn main:app --reload --port 8000
The API will be available at http://localhost:8000
2

Test the API

Create a new job:
curl -X POST http://localhost:8000/api/start-job \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fix my toilet",
    "house_address": "123 Main St, San Jose, CA 95126",
    "zip_code": "95126",
    "price_limit": 250,
    "date_needed": "2025-12-10"
  }'
You’ll receive a response with:
  • job_id - Unique identifier for this job
  • task - Inferred service type (e.g., “plumber”)
  • questions - Array of clarifying questions
3

Complete the job

Submit answers to the clarifying questions:
curl -X POST http://localhost:8000/api/complete-job \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "YOUR_JOB_ID",
    "answers": {
      "q1": "The toilet is constantly running",
      "q2": "Standard toilet, about 10 years old",
      "q3": "No water damage visible"
    }
  }'
This returns matched service providers from your area

​
Quick Start with Full Stack

To run both frontend and backend:
1

Start the backend API

uvicorn main:app --reload --port 8000
2

Start the frontend

In a new terminal:
cd frontend
npm run dev
The frontend will be available at http://localhost:3000
3

Use the web interface

  1. Open http://localhost:3000 in your browser
  2. Enter a service request (e.g., “fix my leaky faucet”)
  3. Fill in your address, zip code, and budget
  4. Answer the AI-generated clarifying questions
  5. View matched providers with estimated prices

​
Enable Voice Calling (Optional)

To enable automated voice negotiation with service providers:
1

Get Twilio credentials

Sign up at twilio.com and get:
  • Account SID
  • Auth Token
  • Phone Number
2

Add Twilio config

Update your config.py or create a .env file:
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=your_twilio_number
DOMAIN=your_public_domain  # e.g., ngrok URL
3

Start the voice backend

cd backend
python app.py
This starts the voice agent service on port 6000
4

Trigger calls

curl -X POST http://localhost:8000/api/start-calls/{job_id}
The voice agent will call each provider and negotiate prices automatically

​
Verify Installation

Check that everything is working: 
curl http://localhost:8000/api/health
Should return: {"status": "healthy"}
python -c "
import asyncio
from services.grok_llm import infer_task

async def test():
    task = await infer_task('fix my leaky faucet')
    print(f'Inferred task: {task}')

asyncio.run(test())
"
Should return something like: Inferred task: plumber
python -c "
from db.models import init_db, get_all_providers
init_db()
providers = get_all_providers()
print(f'Database connected. Provider count: {len(providers)}')
"
Should connect without errors

​
What’s Next?

How It Works

Learn about the complete workflow from query to negotiation

API Reference

Explore all available API endpoints

Configuration

Customize Haggle for your needs

Architecture

Understand the system architecture

​
Troubleshooting

Make sure you’ve installed all dependencies:
pip install -r requirements.txt
Verify your Supabase credentials in config.py:
  • Check that SUPABASE_URL starts with https://
  • Ensure SUPABASE_KEY is the anon/public key
  • Verify the providers table exists
Ensure all required API keys are set:
If port 8000 is already in use, specify a different port:
uvicorn main:app --reload --port 8080
Need Help? Check out the setup guide for detailed installation instructions or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us