Architecture¶
This page is for developers who extend HANI2, deploy it at scale, or write another client. It describes how the server is organised, how it talks to the browser and where the extension points are.
Components¶
browser (React app) ── REST /api/... ──────────┐
│ │
└── WebSocket /api/ws/{sid} ── Hub ── NegotiationSession ── negmas SAOMechanism
├── tools (hani2.tools)
├── support agent (hani2.support_agent)
├── autopilot
└── study (Prolific flow, questionnaires)
| Module | Role |
|---|---|
hani2.cli |
The hani2 command (Typer). |
hani2.server |
The FastAPI app: REST API, WebSocket endpoint, OAuth, static files. |
hani2.hub |
Maps session IDs to sessions and to the open WebSockets; delivers messages. |
hani2.session |
NegotiationSession: scenario, mechanism, draft offer, history, tools, support agent, autopilot. |
hani2.tool_controller |
Tool placement: panes, order, visibility, enable switch. |
hani2.tools |
The Tool base class, the UI components, the registry and the built-in tools. |
hani2.support_agent |
The support agent runtime, its function tools, capabilities, settings and the autopilot. |
hani2.agents |
Opponent specs, groups and the opponent factory. |
hani2.scenario_store, hani2.make_scenarios |
Loading and generating scenarios. |
hani2.study |
The study flow: round planning, practice rounds, questionnaires, Prolific completion. |
hani2.results, hani2.events |
Results files and the SQLite event log. |
hani2.auth |
User store, password hashing, roles, consent. |
hani2.config |
File locations and settings loading. |
hani2.llm_service, hani2.llm_logging, hani2.ollama_fallback |
The message helpers, LLM call logs and the local Ollama fallback. |
hani2.testing |
make_session for browserless tests. |
Process model¶
The server runs as one uvicorn worker process. hani2 always passes workers=1, because every live session is an in-memory Python object: the negmas mechanism, the opponent, the tools and the support agent conversation are not serialisable. Do not run several workers or several replicas behind a load balancer without sticky routing to a single process.
Sessions are kept in the Hub, keyed by a session ID that the server derives from who is connecting:
| Session ID | Who | Key |
|---|---|---|
main:<user> |
A logged-in user at /app (or an anonymous user_<id> in auth.mode = none). |
The hani2_auth login cookie. |
guest:<id> |
A playground visitor at /play. |
The hani2_guest cookie. |
prolific:<pid> |
A Prolific participant at /play?PROLIFIC_PID=<pid>. |
The PID (letters, digits, - and _, up to 64 characters). |
POST /api/session creates the session on first contact (and loads the first scenario) or returns the existing one, so reloading the page or opening a second tab joins the same session. Passing "fresh": true discards the existing session first. All tabs of a session receive the same updates.
A background task removes sessions that have had no open WebSocket for six hours, unless a negotiation is running. Restarting the server drops all sessions; results already written to disk are kept.
Threading¶
HANI2 keeps the event loop free by running all session work in threads.
- Session lock.
NegotiationSession.lockis a re-entrant lock that guards session state. It is held only briefly.run_on_doc(fn)runs a callable under it; support agents and tools use it to read or change state safely. - Step lock.
step_lockserialises stepping the mechanism. Opponent steps, which may wait for a slow LLM, run in a worker thread without holding the session lock, so the UI, the tools and the assistant stay responsive while the opponent thinks. - Worker pool. A process-wide thread pool (
HANI2_WORKERSthreads, default 32) runs mechanism steps, support agent events and any work submitted withsession.submit(fn, ...). - Per-session UI queue. Each session has a single-thread executor that applies UI messages from the browser in arrival order (
submit_ui). Messages that may block on an LLM or on the human (chat,answer,panel_action,extract,generate) go to the worker pool instead, so they never hold up the queue. - Delivery. Sessions call
Hub.push,Hub.push_stateandHub.tool_changedfrom any thread. The hub hands the work to the event loop. State pushes are coalesced (about 20 ms) and tool re-renders are coalesced per tool (about 50 ms), so a burst of changes produces one message. - Timeouts. A timer thread watches the negotiation deadline. When time runs out on the human's turn, it repeats the human's last offer so the mechanism can register the timeout.
WebSocket protocol¶
The browser opens ws(s)://<host>/api/ws/<sid> after POST /api/session returned the sid. The server checks the login cookie for main: sessions (unless auth.mode is none) and the guest cookie for guest: sessions, and closes the socket with code 4401 on a mismatch or 4404 for an unknown session.
All messages are JSON objects with a type. On connect the server sends a full state message and a tool message for every tool.
Client to server¶
type |
Fields | Effect |
|---|---|---|
ping |
Server answers {"type": "pong"}. |
|
load |
scenario_type?, name? |
Load the next scenario. The type and name are honoured only when the user may choose scenarios (admins, or allow_scenario_selection). |
start |
Start the negotiation on the loaded scenario. | |
draft |
values |
Update the counter-offer fields (issue → value). |
draft_text |
text |
Update the message to the partner. |
send |
values?, text?, text_only? |
Send the counter-offer. text_only is honoured for admins only. |
accept |
Accept the partner's current offer. | |
end |
End the negotiation without agreement. | |
tool_input |
id, name, value |
A tool input changed (calls Tool.on_input). |
tool_action |
id, action, payload? |
A tool button or row was clicked (calls Tool.on_action). |
tool_layout |
op, name, position?, pane?, enabled? |
op is move, hide, show, enable, focus or restore. move is ignored when allow_moving_tools is off. |
active_tab |
pane, name |
The user switched tabs in a pane. |
pref |
key, value |
Change a user preference, or an admin setting (admins only). |
layout |
view?, sizes?, collapsed? |
Change the layout. |
chat |
text |
A message to the assistant. |
answer |
text |
The answer to a question the assistant asked. |
support |
op, key?, value? |
Assistant settings: op is enable, capability, autonomy, delivery or reset. |
panel_action |
panel_id, action, payload? |
A button in an assistant panel (calls SupportAgent.on_panel_action). |
close_panel |
panel_id |
Close an assistant panel. |
clear_highlight |
target? |
Remove one highlight, or all when target is missing. |
autopilot |
active, driver? |
Turn autopilot on or off. |
questionnaire |
answers |
Submit the post-negotiation questionnaire. |
opponent |
spec |
Choose the next opponent (admin view only). |
extract |
Fill the offer from the message with the LLM (admins only). | |
generate |
Write a message for the offer with the LLM (admins only). | |
event |
name?, component?, action?, value? |
Write an entry to the event log (default name button_clicked). The bundled frontend does not send it; it is there for custom clients. |
Unknown types are ignored.
Server to client¶
type |
Fields | Meaning |
|---|---|---|
state |
state |
The full session snapshot (see below). Sent on connect and after every state change. |
tool |
id, view |
The rendered components of one tool, or view: null when the tool is switched off. |
history |
items |
The full negotiation history. |
chat |
message |
One new assistant chat message. |
draft |
draft, utility, by_agent |
The counter-offer fields changed; by_agent is true when a tool or the assistant changed them. |
draft_text |
text |
The message field was changed by a tool or the assistant. |
toast |
message, level, duration, action |
Show a notification. |
confirm |
kind, message |
Ask the human to confirm accept or end (sent when the assistant or a tool requests it). |
pong |
Answer to ping. |
NaN and infinite numbers are replaced before sending, so every message is valid JSON.
The state snapshot has these keys: sid, user, display_name, mode, is_admin, admin_mode, phase (idle, ready, starting, running, ended, questionnaire or finished), round, scenario, opponent, negotiation, partner_offer, reserved_value, draft, result, history, tools, active_tabs, prefs, settings, highlights, annotations, layout, agent_panels, board, chat, pending_question, support, autopilot, notice, questionnaire, finish_url, study, can_choose_scenario and next_opponent. Non-admins receive only a few of the admin settings in settings.
REST API¶
All endpoints are under /api. Admin endpoints require an admin login cookie. They return 401 when nobody is logged in and 403 for users who are not admins.
Public and session¶
| Method and path | Purpose |
|---|---|
GET /api/config |
Title, subtitle, version, effective auth mode, OAuth providers, registration and consent flags, whether the playground is on, the active experiment and docs_url. |
GET /api/announcements |
The content of announcements.md. |
GET /api/consent |
The content of consent.md. |
POST /api/consent |
Record consent for the logged-in user (agree, full_name). |
POST /api/session |
Create or join a session. Body: mode (main or guest), query (the page's URL parameters), fresh. Returns {"sid": ...}. |
WS /api/ws/{sid} |
The live channel described above. |
Authentication¶
| Method and path | Purpose |
|---|---|
GET /api/auth/me |
The current user, display name, email, admin flag and consent state. |
POST /api/auth/login |
Log in with username and password. |
POST /api/auth/logout |
Log out. |
POST /api/auth/register |
Register (username, password, confirm, email, confirm_email, full_name, consent). |
POST /api/auth/password |
Change the logged-in user's password (old, new). |
GET /api/oauth/{provider}/login |
Start an OAuth login (github or google). |
GET /api/oauth/{provider}/callback |
The OAuth callback. |
Admin¶
| Method and path | Purpose |
|---|---|
GET, PUT /api/admin/settings/{kind} |
Read or save a settings file. kind is env, llm, support_agent, autopilot (JSON) or consent, announcements, scenario_order, scenario_sets (text, as {"text": ...}). Saving always writes to the settings folder. |
GET /api/admin/meta |
Opponent groups, scenario types and names, tools, capability labels and autopilot drivers, for the console's forms. |
GET /api/admin/results |
All results rows, the column lists and the leaderboard. |
GET /api/admin/results.csv |
All results as one CSV file. |
GET /api/admin/events |
Query the event log (user, session_id, types, since, until, limit, offset). |
GET /api/admin/events/summary |
Event counts and recent sessions. |
GET /api/admin/events.csv |
The full event log as CSV. |
GET, POST /api/admin/users |
List users, or create one (username, password, email, full_name, is_admin). |
PATCH /api/admin/users/{username} |
Set password or is_admin. |
DELETE /api/admin/users/{username} |
Delete a user (not admin, not yourself). |
GET /api/admin/sessions |
Live sessions: user, mode, phase, round, connections, idle seconds, partner, scenario. |
GET /api/admin/llm/status |
Whether the message-helper LLM is configured. |
FastAPI's interactive documentation is available at /docs while the server runs.
Every other path returns the single-page app (index.html), which routes /app, /play, /admin, /login and the other pages in the browser. Built assets are served from /assets.
Frontend¶
The frontend lives in frontend/ and uses React 19, TypeScript, Vite, Tailwind CSS, zustand for state, react-markdown and Plotly.
| Path | Content |
|---|---|
src/store.ts |
The WebSocket client and the session store; applies the server messages. |
src/negotiate/ |
The negotiation page: header, action dock, history thread, tool panes, assistant dock, settings drawer. |
src/pages/ |
The login, registration and consent pages, and the admin console. |
src/ui/ |
Shared pieces: the component renderer for tool views, gauges, plots, markdown, modals, toasts and highlight anchors. |
npm run build type-checks and writes the bundle to src/hani2/web, which the wheel includes. The server serves whatever is in that folder, so a rebuilt frontend needs no Python change. During development, npm run dev serves the app on port 5173 and proxies /api (including WebSockets) to the backend on port 5006.
Tools and support agent panels never ship frontend code. They describe their views with the components in hani2.tools.ui, which the generic renderer in src/ui/Renderer.tsx displays. See Build a tool.
Extension points¶
| What | How |
|---|---|
| Tools | Subclass hani2.tools.base.Tool; register through env.json → tools.extra or a hani2.tools entry point. See Tools. |
| Support agents | Subclass hani2.support_agent.runtime.SupportAgent; set agent_class in support_agent_settings.json. See Support agent. |
| Opponents | Any negmas negotiator class, by dotted path or file: spec. See Opponents. |
| Scenarios | Folders on disk. See Scenarios. |