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¶
Comprehensive analysis of debate performance and quality. |
|
Enumeration of debate phases for structured discussion flow. |
|
Represents a participant in the debate. |
|
Represents a single statement in a debate or discussion. |
|
Represents a debate topic or resolution. |
|
Represents a vote or evaluation from a participant. |
Module Contents¶
- class games.debate.models.DebateAnalysis(/, **data)¶
Bases:
pydantic.BaseModelComprehensive 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)
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 games.debate.models.DebatePhase¶
-
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()¶
Get standard Lincoln-Douglas debate phase sequence.
- Returns:
Ordered phases for Lincoln-Douglas format.
- Return type:
List[DebatePhase]
- classmethod get_oxford_flow()¶
Get standard Oxford-style debate phase sequence.
- Returns:
Ordered phases for Oxford format.
- Return type:
List[DebatePhase]
- classmethod get_parliamentary_flow()¶
Get standard parliamentary debate phase sequence.
- Returns:
Ordered phases for parliamentary format.
- Return type:
List[DebatePhase]
- class games.debate.models.Participant(/, **data)¶
Bases:
pydantic.BaseModelRepresents 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)
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)¶
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)¶
Validate participant role is recognized.
- Parameters:
v (str) – Role to validate.
- Returns:
Validated role string.
- Return type:
- Raises:
ValueError – If role is not supported.
- class games.debate.models.Statement(/, **data)¶
Bases:
pydantic.BaseModelRepresents 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)
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)¶
Validate statement content is not empty and properly formatted.
- Parameters:
v (str) – Content to validate.
- Returns:
Cleaned and validated content.
- Return type:
- Raises:
ValueError – If content is empty or contains only whitespace.
- classmethod validate_timestamp(v)¶
Validate timestamp is in proper ISO format.
- Parameters:
v (str) – Timestamp string to validate.
- Returns:
Validated timestamp string.
- Return type:
- Raises:
ValueError – If timestamp format is invalid.
- class games.debate.models.Topic(/, **data)¶
Bases:
pydantic.BaseModelRepresents 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)
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)¶
Validate and clean keyword list.
- classmethod validate_title(v)¶
Validate topic title is properly formatted.
- Parameters:
v (str) – Title to validate.
- Returns:
Cleaned and validated title.
- Return type:
- Raises:
ValueError – If title is too short or improperly formatted.
- class games.debate.models.Vote(/, **data)¶
Bases:
pydantic.BaseModelRepresents 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)
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.