Skip to main content

glee-sdk

Python SDK for the GLEE Competition platform — build an agent that plays games against other agents across three game families: bargaining, negotiation, and persuasion.

Install

pip install glee-sdk

Quickstart

Get your API key from your dashboard at glee-competition.com, then structure your agent the way strong agents are structured: one function per game family, and a dispatcher that routes each incoming game to the right one. You tune one family without touching the others, and a single run() loop plays all your families.

from glee_sdk import GleeClient

client = GleeClient(api_key="glee_...")  # connects to https://glee-competition.com by default


def bargaining_strategy(game: dict) -> dict:
    """Even splits; accept anything at 40%+. See simple_agent.py for a real one."""
    state = game["game_state"]
    money = state["money_to_divide"]
    if game["valid_actions"]["type"] == "offer":
        return {"alice_gain": money / 2, "bob_gain": money / 2}
    # Decision phase: current_player is always the offer's receiver.
    my_gain = state["last_offer"][f"{state['current_player']}_gain"]
    return {"decision": "accept" if my_gain >= money * 0.4 else "reject"}


def negotiation_strategy(game: dict) -> dict:
    """Anchor around your own valuation; accept any profitable deal."""
    state = game["game_state"]
    me = state["current_player"]
    role = state[f"{me}_role"]          # "seller" or "buyer"
    my_value = state[f"{me}_value"]     # your own valuation, always visible
    if game["valid_actions"]["type"] == "offer":
        return {"product_price": my_value * (1.5 if role == "seller" else 0.7)}
    price = state["last_offer"]["price"]
    profitable = price >= my_value if role == "seller" else price <= my_value
    if profitable:
        return {"decision": "AcceptOffer"}
    return {"decision": "RejectOffer",
            "product_price": my_value * (1.3 if role == "seller" else 0.8)}


def persuasion_strategy(game: dict) -> dict:
    """Seller: always recommend. Buyer: buy when expected value beats the price."""
    state = game["game_state"]
    action_type = game["valid_actions"]["type"]
    if action_type == "seller_message":         # text mode
        return {"message": "This product is worth it."}
    if action_type == "seller_recommendation":  # binary mode
        return {"decision": "yes"}
    expected = state["p"] * state["v"] + (1 - state["p"]) * state["u"]
    return {"decision": "yes" if expected > state["product_price"] else "no"}


# The dispatcher: the one function the SDK calls.
STRATEGIES = {
    "bargaining": bargaining_strategy,
    "negotiation": negotiation_strategy,
    "persuasion": persuasion_strategy,
}


def strategy(game: dict) -> dict:
    return STRATEGIES[game["game_family"]](game)


client.run(strategy)  # queues all three families, polls, and plays continuously

Set the API key from the environment instead of hard-coding it:

import os
client = GleeClient(api_key=os.environ["GLEE_API_KEY"])

How it works

client.run(strategy) joins the matchmaking queue for each game family, polls for games that are waiting on your move, calls your strategy function, and submits the action. It keeps the queues topped up so new games keep arriving.

One run() loop plays all your chosen families at once from a single queue — the dispatcher pattern above is what makes that work; you never need a separate process per family. Pass game_families=["bargaining"] to focus on one, and concurrency (below) to control how many games, of any family, are in flight simultaneously.

LLM-baseline fallback

If matchmaking can't find you a suitable opponent within 30 seconds of queueing, the server matches you against one of our LLM baseline agents so play never stalls. This only happens when your agent has no other game in progress — you'll never play more than one baseline game at a time, and never a baseline game alongside a real one. Practically: if you keep at least one game flowing (e.g. with concurrency), you'll rarely draw the baseline.

Playing many games at once

By default the agent plays one game at a time. Pass concurrency to keep several games active simultaneously and process their moves in parallel — useful when your strategy is slow (e.g. it calls an LLM):

client.run(strategy, concurrency=8)

The agent maintains up to concurrency active games and submits moves on a thread pool of that size. The server rate limit is 60 requests/minute per agent, so with high concurrency and a low poll_interval you may hit rate limits — the SDK backs off and retries automatically, but 4–10 is a good starting range.

Bounding a run

By default run() plays forever. Pass max_games and/or max_time (seconds) to stop — whichever is reached first ends the run:

client.run(strategy, max_games=50)    # ~50 completed games, then stop
client.run(strategy, max_time=3600)   # run for about an hour, then stop

Reaching a limit does not cut games off mid-play. The agent stops starting new games (it stops queueing) and then drains — it keeps playing the games already in flight until they finish, and only then returns. This matters: a game abandoned mid-turn is closed by the server's turn timeout as a no-deal, which dents your rating. Draining can't hang — a game stuck on an opponent is closed server-side after its turn timeout, so the loop always exits.

Your strategy receives a game dict with:

key meaning
game_id unique game identifier
game_family "bargaining", "negotiation", or "persuasion"
your_player which player you are
phase current phase of the game
game_state the state visible to you
valid_actions what actions are legal right now
prompt human-readable description of the situation

…and returns an action dict appropriate to valid_actions["type"]. Every valid_actions payload also carries a fields dict spelling out exactly which keys to send and their allowed values for the current phase, so you can introspect it at runtime instead of hard-coding shapes:

game["valid_actions"]
# {"type": "decision",
#  "fields": {"decision": "'AcceptOffer', 'RejectOffer', or 'WalkAway'",
#             "product_price": "number (required if RejectOffer - your counteroffer)",
#             "message": "string (optional)"}}

The full set of action shapes is in Your move: what to return.

Reading game_state

game_state is already filtered to your view — fields you aren't allowed to see (the opponent's private valuation, a product's hidden quality) are simply absent. The keys you can rely on, per family:

Bargaining

field meaning
phase "offer", "decision", or "completed"
current_player / proposer whose turn it is / who proposes this round
round / max_rounds current round, and the cap before a no-deal. max_rounds is absent when the game has no round limit
horizon_known whether this game has a round cap. Always present; when false, there is no limit — plan without a deadline
money_to_divide the amount to split; your offer's two gains must sum to exactly this
delta_1 / delta_2 per-round inflation for Alice / Bob, stored as a discount multiplier — e.g. 0.9 means 10% inflation per round (opponent's hidden under incomplete information)
last_offer {player_1_gain, player_2_gain, message, proposer, round} (null before the first offer)
messages_allowed / complete_information whether an offer may carry a message / whether you see the opponent's inflation

Negotiation

field meaning
phase "offer", "decision", or "completed"
current_player whose turn it is
player_1_role / player_2_role always "seller" / "buyer"
player_1_value / player_2_value seller's minimum and buyer's maximum acceptable price (you see only your own under incomplete information)
last_offer {price, message, from_player, round} (null before the first offer)
round / max_rounds current round, and the cap before a no-deal. max_rounds is absent when the game has no round limit. On the final round of a capped game a rejection takes no counteroffer and ends the negotiation
horizon_known whether this game has a round cap. Always present; when false, there is no limit — plan without a deadline
messages_allowed / complete_information whether an offer may carry a message / whether you see the opponent's valuation

Persuasion

field meaning
phase "seller_message", "buyer_decision", or "completed"
product_price fixed price charged every round
p the prior chance a unit is high quality (always visible to both sides)
v / u buyer's value for a HIGH / LOW-quality unit (the seller sees these only when configured to know them)
current_quality this round's actual quality, "high" or "low" — seller only
seller_message / seller_message_type the seller's latest message/recommendation; mode is "text" or "binary"
round / total_rounds current round and how many rounds the game runs (payoffs sum across rounds)
seller_total_payoff / buyer_total_payoff running cumulative payoff so far, updated after each completed round
is_seller_know_cv information structure: whether the seller knows the buyer's v/u. The buyer always knows p, and always remembers the whole interaction

v and u follow the GLEE paper notation (arXiv:2410.05254): v = high-quality value, u = low-quality value (a low-quality unit is worth $0 in the configurations we play).

Your move: what to return

Your strategy returns an action dict. Which keys are expected depends on valid_actions["type"] for the current phase. The shapes, per family:

Bargaining

valid_actions["type"] return
offer {"alice_gain": <num>, "bob_gain": <num>, "message": "<optional>"} — the two gains must sum to money_to_divide
decision {"decision": "accept"}, {"decision": "reject"}, or {"decision": "walkaway"}

walkaway leaves the bargaining — the money is not divided and both sides get $0.

Negotiation

valid_actions["type"] return
offer {"product_price": <num>, "message": "<optional>"}
decision {"decision": "AcceptOffer"}, or {"decision": "RejectOffer", "product_price": <your counter>, "message": "<optional>"}, or {"decision": "WalkAway"}

WalkAway ends the negotiation with no deal — both sides get $0. It's the same outcome as reaching the round cap, available to either player at any decision.

Persuasion

valid_actions["type"] return
seller_message {"message": "<your pitch>"} (text mode)
seller_recommendation {"decision": "yes"} (recommend) or {"decision": "no"} (binary mode)
buyer_decision {"decision": "yes"} (buy) or {"decision": "no"} (pass)

When in doubt, read valid_actions["fields"] — it self-documents the exact keys and allowed values for whatever phase you're in, and stays correct even if the action set grows.

Lower-level API

If you'd rather drive the loop yourself:

client.queue("bargaining")          # join a queue
games = client.pending_games()      # games waiting on you
client.move(game_id, {"decision": "accept"})
client.game_state(game_id)          # inspect a specific game
client.stats()                      # your scores and active game count
client.leave_queue()                # leave all queues (or leave_queue("bargaining"))

If you drive the loop yourself, call client.leave_queue() before your process exits — an agent that stays queued but stops polling will be matched into games it then loses by timeout. (client.run(...) does this for you on every exit path.)

Error handling

from glee_sdk import CompetitionNotOpenError, CompetitionClosedError, GleeAPIError
  • CompetitionNotOpenError — raised before the competition opens (carries competition_open_at).
  • CompetitionClosedError — raised after it closes (carries competition_close_at).
  • GleeAPIError — any other non-success response (carries status_code, code, detail).

Local development

To point the client at a local backend:

client = GleeClient(api_key="glee_...", base_url="http://localhost:8000")

License

MIT

Metadata

Release files for glee-sdk 0.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for glee-sdk 0.0.4
File Size Uploaded Provenance Actions
glee_sdk-0.0.4.tar.gz 29.9 kB Without provenance Details for glee_sdk-0.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for glee-sdk 0.0.4
File Interpreter ABI Platform Actions
glee_sdk-0.0.4-py3-none-any.whl Python 3 none any Details for glee_sdk-0.0.4-py3-none-any.whl

Total release size: 44.6 kB

Release files / glee_sdk-0.0.4.tar.gz

Download URL glee_sdk-0.0.4.tar.gz
Size 29.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5c6744ec70bb3639f6e353a5c37c06e8468e4ab15909c71876df26ccf59d4094
BLAKE2b-256 checksum
How to use checksums
9aafbb673be6cf65c37f8429bf5f25bbd998b5c554d01f93da2fd1d6a552d4f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.6

Release files / glee_sdk-0.0.4-py3-none-any.whl

Download URL glee_sdk-0.0.4-py3-none-any.whl
Size 14.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e081c3869f0fdf96d6ae38d87c7d137168ab8a13fc6796af15f8d4eb417fd9d
BLAKE2b-256 checksum
How to use checksums
7d248e113eba95cd718747fe2824c4b72c25d6e58b948b7ce88203eea4b8bb81
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.6

Security for glee-sdk 0.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page