haive.games.debate.models¶

Pydantic models for debate game components.

This module defines the core data models used in the debate game implementation, including statements, participants, topics, votes, and debate phases. All models use Pydantic for validation and serialization with comprehensive field documentation.

The models support various debate formats including parliamentary, Oxford-style, and Lincoln-Douglas debates with proper type safety and validation.

Examples

Creating a debate statement:

statement = Statement(
    content="I believe AI regulation is essential for safety",
    speaker_id="participant_1",
    statement_type="opening",
    timestamp="2024-01-08T15:30:00Z"
)

Setting up a debate topic:

topic = Topic(
    title="AI Should Be Regulated by Government",
    description="Debate whether artificial intelligence development should be subject to government oversight",
    keywords=["artificial intelligence", "regulation", "government oversight"]
)

Creating a participant:

participant = Participant(
    id="debater_1",
    name="Dr. Smith",
    role="debater",
    position="pro",
    expertise=["AI ethics", "technology policy"]
)

Classes¶

`DebateAnalysis`	Comprehensive analysis of debate performance and quality.
`DebatePhase`	Enumeration of debate phases for structured discussion flow.
`Participant`	Represents a participant in the debate.
`Statement`	Represents a single statement in a debate or discussion.
`Topic`	Represents a debate topic or resolution.
`Vote`	Represents a vote or evaluation from a participant.

Module Contents¶

class haive.games.debate.models.DebateAnalysis(/, **data)[source]¶

Bases: pydantic.BaseModel

Comprehensive analysis of debate performance and quality.

This model provides structured evaluation of debate participants, arguments, and overall debate quality. It supports both automated AI analysis and human judge evaluations with detailed scoring and qualitative feedback.

Parameters:: data (Any)

participant_scores¶

Individual performance scores.

Type:: Dict[str, float]

argument_quality¶

Overall argument quality assessment.

Type:: float

engagement_level¶

Participant engagement and interaction.

Type:: float

factual_accuracy¶

Accuracy of claims and evidence.

Type:: float

rhetorical_effectiveness¶

Persuasive power and delivery.

Type:: float

winner¶

Determined winner if applicable.

Type:: Optional[str]

key_arguments¶

Most significant arguments presented.

Type:: List[str]

strengths¶

Notable strengths in the debate.

Type:: List[str]

weaknesses¶

Areas needing improvement.

Type:: List[str]

recommendations¶

Suggestions for future debates.

Type:: List[str]

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class haive.games.debate.models.DebatePhase[source]¶

Bases: str, enum.Enum

Enumeration of debate phases for structured discussion flow.

These phases represent the standard progression of formal debates, providing structure and ensuring all participants have appropriate opportunities to present arguments, respond to opponents, and reach conclusions. Different debate formats may use subsets of these phases.

The phases are designed to support various debate formats including parliamentary, Oxford-style, Lincoln-Douglas, and custom formats while maintaining logical flow and fairness.

SETUP¶: Initial preparation and rule establishment.

OPENING_STATEMENTS¶: Initial position presentations.

DISCUSSION¶: Open floor discussion and argument development.

REBUTTAL¶: Direct responses to opposing arguments.

QUESTIONS¶: Cross-examination and clarification phase.

CLOSING_STATEMENTS¶: Final position summaries.

VOTING¶: Decision-making and evaluation phase.

JUDGMENT¶: Official results and analysis.

CONCLUSION¶: Final wrap-up and documentation.

Examples

Parliamentary debate flow:

phases = [
    DebatePhase.SETUP,
    DebatePhase.OPENING_STATEMENTS,
    DebatePhase.REBUTTAL,
    DebatePhase.CLOSING_STATEMENTS,
    DebatePhase.JUDGMENT
]

Oxford-style debate:

phases = [
    DebatePhase.SETUP,
    DebatePhase.OPENING_STATEMENTS,
    DebatePhase.DISCUSSION,
    DebatePhase.QUESTIONS,
    DebatePhase.CLOSING_STATEMENTS,
    DebatePhase.VOTING,
    DebatePhase.CONCLUSION
]

Lincoln-Douglas format:

phases = [
    DebatePhase.SETUP,
    DebatePhase.OPENING_STATEMENTS,
    DebatePhase.QUESTIONS,  # Cross-examination
    DebatePhase.REBUTTAL,
    DebatePhase.CLOSING_STATEMENTS,
    DebatePhase.JUDGMENT
]

Note

Phase transitions should be managed by the debate agent to ensure proper timing and participant readiness. Some phases may be repeated (e.g., multiple rebuttal rounds) or skipped based on debate format.

Initialize self. See help(type(self)) for accurate signature.

classmethod get_lincoln_douglas_flow()[source]¶

Get standard Lincoln-Douglas debate phase sequence.

Returns:: Ordered phases for Lincoln-Douglas format.
Return type:: List[DebatePhase]

classmethod get_oxford_flow()[source]¶

Get standard Oxford-style debate phase sequence.

Returns:: Ordered phases for Oxford format.
Return type:: List[DebatePhase]

classmethod get_parliamentary_flow()[source]¶

Get standard parliamentary debate phase sequence.

Returns:: Ordered phases for parliamentary format.
Return type:: List[DebatePhase]

class haive.games.debate.models.Participant(/, **data)[source]¶

Bases: pydantic.BaseModel

Represents a participant in the debate.

A participant can be a debater, judge, moderator, or audience member with specific roles, expertise, and characteristics that influence their contribution to the debate. This model supports AI-powered participants with configurable personalities and human participants with tracked metadata.

Participants can have positions (pro/con/neutral), expertise areas that inform their arguments, and personality traits that influence their debating style and decision-making patterns.

Parameters:: data (Any)

id¶

Unique identifier for the participant.

Type:: str

name¶

Display name shown in the debate interface.

Type:: str

role¶

Function in the debate (debater, judge, moderator, audience).

Type:: str

position¶

Stance on the topic (pro, con, neutral).

Type:: Optional[str]

persona¶

Personality traits and characteristics.

Type:: Optional[Dict[str, str]]

expertise¶

Subject matter expertise areas.

Type:: List[str]

bias¶

Inherent bias level for realistic modeling.

Type:: Optional[float]

Examples

Creating a pro debater:

debater = Participant(
    id="pro_debater_1",
    name="Dr. Sarah Chen",
    role="debater",
    position="pro",
    persona={
        "style": "analytical",
        "approach": "evidence-based",
        "temperament": "calm"
    },
    expertise=["artificial intelligence", "technology policy", "ethics"],
    bias=0.2
)

Creating a neutral moderator:

moderator = Participant(
    id="moderator_1",
    name="Judge Williams",
    role="moderator",
    position="neutral",
    persona={
        "style": "formal",
        "approach": "procedural",
        "fairness": "strict"
    },
    expertise=["debate procedures", "parliamentary law"]
)

Creating a specialized judge:

judge = Participant(
    id="judge_1",
    name="Prof. Martinez",
    role="judge",
    position="neutral",
    expertise=["economics", "public policy", "data analysis"],
    bias=-0.1
)

Note

Bias values range from -1.0 (strongly biased toward con position) to +1.0 (strongly biased toward pro position), with 0.0 being perfectly neutral. Small bias values (±0.1 to ±0.3) create realistic human-like tendencies without compromising debate quality.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_position(v)[source]¶

Validate debate position if provided.

Parameters:: v (Optional[str]) – Position to validate.
Returns:: Validated position or None.
Return type:: Optional[str]
Raises:: ValueError – If position is not valid.

classmethod validate_role(v)[source]¶

Validate participant role is recognized.

Parameters:: v (str) – Role to validate.
Returns:: Validated role string.
Return type:: str
Raises:: ValueError – If role is not supported.

class haive.games.debate.models.Statement(/, **data)[source]¶

Bases: pydantic.BaseModel

Represents a single statement in a debate or discussion.

A statement is the fundamental unit of discourse in a debate, containing the speaker’s argument, position, or response. Each statement includes metadata for tracking, analysis, and proper debate flow management.

This model supports various statement types including opening statements, rebuttals, questions, and closing arguments. It also tracks references, sentiment analysis, and targeting for structured debate formats.

Parameters:: data (Any)

content¶

The actual text content of the statement.

Type:: str

speaker_id¶

Unique identifier of the participant making the statement.

Type:: str

target_id¶

ID of targeted participant for directed statements.

Type:: Optional[str]

statement_type¶

Category of statement for debate flow management.

Type:: str

references¶

Citations, sources, or evidence supporting the statement.

Type:: List[str]

sentiment¶

Sentiment analysis score if available.

Type:: Optional[float]

timestamp¶

ISO format timestamp when the statement was made.

Type:: str

Examples

Creating an opening statement:

opening = Statement(
    content="Government regulation of AI is necessary to prevent harmful outcomes",
    speaker_id="pro_debater_1",
    statement_type="opening",
    references=["AI Safety Research Paper 2024"],
    timestamp="2024-01-08T15:30:00Z"
)

Creating a rebuttal with targeting:

rebuttal = Statement(
    content="The previous speaker's concerns about innovation are unfounded",
    speaker_id="con_debater_1",
    target_id="pro_debater_1",
    statement_type="rebuttal",
    timestamp="2024-01-08T15:35:00Z"
)

Creating a question:

question = Statement(
    content="Can you provide specific examples of AI harm that regulation would prevent?",
    speaker_id="moderator",
    target_id="pro_debater_1",
    statement_type="question",
    timestamp="2024-01-08T15:40:00Z"
)

Note

Statement types should follow debate format conventions. Common types include: “opening”, “rebuttal”, “question”, “answer”, “closing”, “point_of_information”, “point_of_order”.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_content(v)[source]¶

Validate statement content is not empty and properly formatted.

Parameters:: v (str) – Content to validate.
Returns:: Cleaned and validated content.
Return type:: str
Raises:: ValueError – If content is empty or contains only whitespace.

classmethod validate_timestamp(v)[source]¶

Validate timestamp is in proper ISO format.

Parameters:: v (str) – Timestamp string to validate.
Returns:: Validated timestamp string.
Return type:: str
Raises:: ValueError – If timestamp format is invalid.

class haive.games.debate.models.Topic(/, **data)[source]¶

Bases: pydantic.BaseModel

Represents a debate topic or resolution.

A topic defines the subject matter for a debate, including the resolution to be argued, background context, and any constraints or guidelines for the discussion. Topics can range from simple yes/no propositions to complex policy discussions.

This model supports various debate formats by allowing flexible topic definition with keywords for research and constraints for format-specific rules or limitations.

Parameters:: data (Any)

title¶

The main resolution or question being debated.

Type:: str

description¶

Detailed background and context for the topic.

Type:: str

keywords¶

Key terms for research and fact-checking.

Type:: List[str]

constraints¶

Format-specific rules or limitations.

Type:: Optional[Dict[str, str]]

Examples

Simple policy topic:

topic = Topic(
    title="This House Believes That Social Media Does More Harm Than Good",
    description="Debate the overall impact of social media platforms on society, considering both benefits and drawbacks",
    keywords=["social media", "mental health", "democracy", "privacy"],
    constraints={"time_limit": "8 minutes per speaker", "format": "Oxford"}
)

Technical topic with research areas:

topic = Topic(
    title="AI Development Should Prioritize Safety Over Speed",
    description="Consider whether artificial intelligence research should emphasize safety measures even if it slows development",
    keywords=["AI safety", "research ethics", "technological progress", "risk assessment"],
    constraints={
        "evidence_required": "true",
        "fact_checking": "enabled",
        "research_time": "30 minutes"
    }
)

Philosophical topic:

topic = Topic(
    title="Justice Ought to Take Precedence Over Security",
    description="A philosophical examination of the tension between individual rights and collective safety",
    keywords=["justice", "security", "individual rights", "social contract"],
    constraints={"format": "Lincoln-Douglas", "framework_required": "true"}
)

Note

Topic titles should be clear, debatable propositions. For formal debates, use standard resolution formats like “This House Believes…” or “Resolved: …” depending on the debate format.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_keywords(v)[source]¶

Validate and clean keyword list.

Parameters:: v (List[str]) – Keywords to validate.
Returns:: Cleaned list of non-empty keywords.
Return type:: List[str]

classmethod validate_title(v)[source]¶

Validate topic title is properly formatted.

Parameters:: v (str) – Title to validate.
Returns:: Cleaned and validated title.
Return type:: str
Raises:: ValueError – If title is too short or improperly formatted.

class haive.games.debate.models.Vote(/, **data)[source]¶

Bases: pydantic.BaseModel

Represents a vote or evaluation from a participant.

Votes are used for various purposes in debates including final judgments, audience polling, quality ratings, and procedural decisions. The flexible vote_value field supports different voting systems (binary, numeric, ranked).

Votes can target specific participants (for best speaker awards), statements (for argument quality), or the overall debate topic (for winner determination). The reasoning field provides transparency and educational value.

Parameters:: data (Any)

voter_id¶

Unique identifier of the participant casting the vote.

Type:: str

vote_value¶

The actual vote (yes/no, 1-10, ranking).

Type:: Union[str, int, float]

target_id¶

What/who is being voted on (participant, statement, topic).

Type:: Optional[str]

reason¶

Explanation or justification for the vote.

Type:: Optional[str]

Examples

Binary topic vote:

topic_vote = Vote(
    voter_id="judge_1",
    vote_value="pro",
    target_id="main_topic",
    reason="The pro side provided more compelling evidence and stronger logical arguments"
)

Numeric quality rating:

quality_vote = Vote(
    voter_id="audience_member_3",
    vote_value=8.5,
    target_id="statement_15",
    reason="Excellent use of data and clear reasoning, but could have addressed counterarguments"
)

Best speaker vote:

speaker_vote = Vote(
    voter_id="judge_2",
    vote_value="winner",
    target_id="pro_debater_1",
    reason="Outstanding rhetorical skills and effective rebuttal strategy"
)

Procedural vote:

procedural_vote = Vote(
    voter_id="moderator",
    vote_value="approve",
    target_id="time_extension_request",
    reason="Complex topic warrants additional time for thorough discussion"
)

Note

Vote values should be consistent within each voting context. Use strings for categorical votes (“pro”, “con”, “abstain”), numbers for ratings (1-10 scales), and structured data for ranked choices.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_vote_value(v)[source]¶

Validate vote value is reasonable.

Parameters:: v (Union[str, int, float]) – Vote value to validate.
Returns:: Validated vote value.
Return type:: Union[str, int, float]
Raises:: ValueError – If vote value is invalid.