Human-Agent Negotiation Interface (HANI)

HANI is a web-based interface for conducting negotiations between humans and AI agents. It provides a rich set of tools for analyzing negotiation dynamics, making offers, and understanding your negotiation partner's behavior.

📖 Full documentation: autoneg.github.io/hani — installation, quick start, authentication, scenarios, Prolific integration, and more.

🎮 Try it now: anac.cs.brown.edu/hanplay/app — public playground, no signup required.

Quick Start

Installation

pip install hani

Initial Setup

Run the setup command to initialize your configuration:

hani setup

This creates the settings directory at ~/negmas/hani/settings/ with:

• env.json - Main configuration file
• users.json - User credentials
• scenarios/ - Default negotiation scenarios
• Other configuration files

Running the App

hani

This starts both the main app (port 5006) and guest/playground (port 5008).

Then open your browser to http://localhost:5006 and log in:

• Username: admin or user
• Password: adminpass or userpass (defaults, change in env.json)

CLI Commands

Command	Description
hani	Start all services (main app + guest playground)
hani setup	Initialize settings directory with default configuration
hani main	Start only the main app (default port 5006)
hani guest	Start only the guest/playground app (default port 5008)
hani auth	Show OAuth setup instructions
hani --help	Show all available commands and options

Each command accepts a --port flag (e.g. hani guest --port 12000, hani-app --port 6006, hani-reg --port 5107). The top-level hani command takes --main-port / --guest-port to override both services at once. Equivalent env vars: HANI_PORT, HANI_GUEST_PORT, HANI_REG_PORT.

For paid Prolific studies, see docs/prolific.md.

Command Options

# Start with specific agent types
hani --agents "AspirationNegotiator,helpers.AgentK"

# Start without opening browser
hani main --no-browser

# Run setup and overwrite existing files
hani setup --force

# Set custom admin password during setup
hani setup --admin-password "my-secure-password"

Configuration

HANI uses a JSON configuration file located at ~/negmas/hani/settings/env.json.

Basic Configuration

{
    "urls": {
        "app": "http://localhost:5006",
        "playground": "http://localhost:5008"
    },
    "admin": {
        "password": "adminpass",
        "emails": []
    },
    "auth": {
        "mode": "password",
        "cookie_secret": "change-this-in-production"
    }
}

Configuration Options

Setting	Description	Default
urls.app	Main app URL	http://localhost:5006
urls.playground	Guest playground URL	http://localhost:5008
admin.password	Admin user password	adminpass
admin.emails	Admin emails for OAuth mode	[]
auth.mode	Auth mode: password, dual, oauth, auto	password
auth.cookie_secret	Session cookie secret	(default value)
auth.enforce_consent	Require consent form before negotiation	false

Features

Negotiation Interface

• Action Panel: Make offers by setting values for each negotiation issue
• History View: See the full negotiation history with offers from both parties
• Utility Display: Real-time feedback on how good each offer is for you

AI-Powered Tools

When configured with an LLM API key, HANI provides:

• Text-to-Outcome Extraction: Extract structured offers from natural language messages
• Outcome-to-Text Generation: Generate natural language descriptions of your offers
• Response Generator: Describe what you want to say and let AI generate both the message and offer

Analysis Tools

• Utility Plot: Visualize utility over time
• Outcome Plot: See where offers fall in the outcome space
• Preferences View: Understand your preferences for the negotiation
• Negotiation Trace: Detailed log of all negotiation events

Authentication

HANI supports multiple authentication modes configured via auth.mode in env.json.

Password Authentication (Default)

Best for local development and small deployments.

{
    "auth": {
        "mode": "password"
    }
}

• Users stored in ~/negmas/hani/settings/users.json
• Default users: admin/adminpass and user/userpass
• New users can register via /register endpoint

Dual Authentication (Password + OAuth)

Allows users to log in with either password or OAuth providers.

{
    "auth": {
        "mode": "dual"
    },
    "oauth": {
        "redirect_uri": "http://localhost:5006",
        "providers": {
            "github": {
                "enabled": true,
                "key": "your-github-client-id",
                "secret": "your-github-client-secret"
            },
            "google": {
                "enabled": true,
                "key": "your-google-client-id",
                "secret": "your-google-client-secret"
            }
        }
    }
}

Setting Up OAuth

Run hani auth to see detailed setup instructions. Here's a summary:

GitHub OAuth

1. Go to https://github.com/settings/developers
2. Create a new OAuth App
3. Set Homepage URL: http://localhost:5006
4. Set Authorization callback URL: http://localhost:5006/oauth/callback
5. Copy Client ID and Client Secret to env.json

Google OAuth

1. Go to https://console.cloud.google.com/apis/credentials
2. Create OAuth 2.0 Client ID (Web application)
3. Add authorized redirect URI: http://localhost:5006/oauth/callback
4. Copy Client ID and Client Secret to env.json

OAuth Admin Access

In OAuth/dual mode, admin access is granted to users whose email is in the admin.emails list:

{
    "admin": {
        "emails": ["admin@example.com", "another-admin@example.com"]
    }
}

Auto Mode

When auth.mode is auto:

• Uses OAuth if OAuth credentials are configured
• Falls back to password authentication otherwise

Configuring Agent/Negotiator Types

HANI allows you to specify which negotiator types the AI opponent can use.

Command-Line Argument (Recommended)

# Use specific NegMAS negotiators
hani --agents "AspirationNegotiator,BoulwareTBNegotiator,ConcederTBNegotiator"

# Mix of different negotiator types
hani --agents "AspirationNegotiator,helpers.AgentK,helpers.Atlas3,LLMHybridNegotiator"

# Use only HANI custom negotiators
hani --agents "helpers.AgentK,helpers.HardHeaded,helpers.AverageTitForTat"

Agent Groups

Use group syntax to select categories of agents:

# All LLM-based negotiators
hani --agents ":llm"

# All template-based negotiators
hani --agents ":template"

# All NegMAS negotiators
hani --agents ":negmas"

# Combine groups
hani --agents ":llm,:template"

Supported Negotiator Namespaces

NegMAS Negotiators (default namespace)

hani --agents "AspirationNegotiator,BoulwareTBNegotiator,NaiveTitForTatNegotiator"

HANI Helper Negotiators

hani --agents "helpers.AgentK,helpers.Atlas3,helpers.CUHKAgent,helpers.HardHeaded"

Genius Negotiators

hani --agents "genius.Atlas3,genius.AgentK,genius.HardHeaded"

LLM-based Negotiators

hani --agents "LLMHybridNegotiator,LLMBoulwareTBNegotiator,LLMConcederTBNegotiator"

Custom Negotiators from Files

# Load from a Python file
hani --agents "file:mynegotiator.MyNegotiator"

# With path
hani --agents "file:agents/custom/myneg.MyNegotiator"

Customization

Announcements

Create ~/negmas/hani/settings/announcements.md to display custom announcements on the welcome screen.

Scenarios

Custom scenarios can be placed in ~/negmas/hani/settings/scenarios/. Run hani setup to copy the default scenarios as examples.

Consent Form

Edit ~/negmas/hani/settings/consent.md to customize the consent form. Enable it with:

{
    "auth": {
        "enforce_consent": true
    }
}

How It Works

1. Scenario Loading: A negotiation scenario is loaded with defined issues (e.g., price, quantity) and preferences for each party.

2. Turn-Based Negotiation: You and the AI agent take turns making offers. Each offer specifies values for all issues.

3. Decision Making: On each turn, you can:

   • Send an offer: Propose specific values for each issue
   • Accept: Accept the current offer from your partner
   • End Negotiation: Terminate without agreement

4. Text Messages: Optionally include natural language messages with your offers to communicate intent.

5. Analysis: Use the built-in tools to understand the negotiation dynamics and make informed decisions.

LLM Configuration (Admin)

Administrators can configure LLM settings in the sidebar under "LLM Settings":

• Provider: OpenAI or Anthropic
• Model: The model to use (e.g., gpt-4o-mini, claude-3-haiku)
• Temperature: Controls response randomness (0.0-2.0)
• Prompts: Customize extraction and generation prompts

LLM API keys can be set in ~/negmas/hani/settings/llm_settings.json or via environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY).

Development

Contributing

To contribute, clone this repo and install development dependencies:

git clone https://github.com/autoneg/hani.git
cd hani
pip install -e ".[dev]"

Running in Development Mode

hani dev

This enables auto-reload when files change.

Project Structure

src/hani/
├── app.py              # Main application
├── auth.py             # Authentication utilities
├── common.py           # Shared configuration
├── dual_auth.py        # OAuth and dual auth handlers
├── llm_service.py      # LLM integration
├── run.py              # CLI entry point
├── tools/              # Analysis tools
│   ├── generator.py    # Response generator tool
│   ├── preferences.py  # Preferences viewer
│   └── ...
├── scenarios/          # Built-in negotiation scenarios
├── sample_scenarios/   # Default scenarios copied on setup
└── default_settings/   # Default configuration files

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for details.

Author

Yasser Mohammad (yasserfarouk@gmail.com)