habermas-machine

habermas-machine packages the core deliberation, ranking, and social-choice components used to run Habermas Machine experiments.

Install

Install the core package:

uv add habermas-machine

Install with provider extras when you need live model clients:

uv add "habermas-machine[all]"

Available extras:

• google
• anthropic
• together
• modal
• openrouter
• all

Optional Anthropic structured output

The standard two-step generator can use Anthropic's native JSON-schema decoding:

from habermas_machine import models

client = models.LLMCLient.ANTHROPIC.get_client("your-supported-claude-model")
statement_model = models.StatementModel.TWO_STEP_DIVERSE.get_model(
    llm_client=client,
    language="en",
    structured_output=True,
)

Use this model as the machine's diverse_statement_model (or register it in statement_models) and call HabermasMachine.mediate() as usual. In habermas_api, enable the option where TWO_STEP_DIVERSE is constructed after updating the installed HM package. Parsed candidate fields keep their existing shape, so the website's frontend does not need to change. Raw model_response strings, including candidates.all_text_model_responses in the machine result, contain JSON in structured mode instead of tagged text. Analysis scripts that re-parse those responses must account for the selected format.

Both steps use the same drafting instructions as the tagged prompts, with JSON format instructions for English and Arabic (other locales retain the English fallback). Results remain StatementResult objects. Attempt limits and failed response logging are retained; retries never switch formats. Structured mode requires exactly the requested number of approach strings, each longer than five characters after trimming, and rejects the whole list if any approach is invalid. The tagged path retains its existing filtering of short approaches. Statement length checks remain in place, and incomplete/refused output can still fail validation.

The default token budget is 20,000, within the Anthropic SDK's default non-streaming request limit. Unexpected response stop reasons (such as max_tokens and refusal) are logged with raw text, token usage, and request ID when available. Request/SDK errors are logged with the original exception and traceback. Invalid requests and the SDK's Streaming is required errors propagate immediately; other request failures retain their existing retry behavior.

The default is False. Structured mode currently requires an Anthropic model supporting structured output and the stock two-step prompts/parsers. It supports only generate_diverse_statement; single-statement and batch methods reject the option rather than using tagged output. Other clients/generators remain unchanged.

Development

Sync a local development environment with tests and release tooling:

uv sync --group dev --extra all

Run tests:

uv run pytest

Build distribution artifacts:

uv build
uv run twine check dist/*

Releases

• GitHub Actions runs CI on pushes and pull requests.
  • Runs unit tests.
  • Builds the package.
  • Tests pacakge is installable.
  • Publishes a unique dev build to TestPyPI through trusted publishing.
• Creating a non-prerelease GitHub release publishes the tagged version to PyPI through trusted publishing.